@bsb/base 9.0.0

package/lib/base/base.js

@@ -0,0 +1,182 @@
+"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.MS_PER_NS = exports.NS_PER_SEC = exports.BaseWithObservableAndConfig = exports.BaseWithObservable = exports.BaseWithConfig = exports.Base = exports.MainBase = void 0;
+const ObservableBackend_1 = require("./ObservableBackend");
+/**
+ * @hidden
+ */
+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}
+     */
+    appId = "tbd";
+    /**
+     * 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}
+     */
+    mode = "development";
+    /**
+     * The current working directory of the app
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/MainBase.html#cwd | API: MainBase.cwd}
+     */
+    cwd;
+    /**
+     * The current working directory of the plugin
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/MainBase.html#packageCwd | API: MainBase.packageCwd}
+     */
+    packageCwd;
+    /**
+     * The current working directory of the service
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/MainBase.html#pluginCwd | API: MainBase.pluginCwd}
+     */
+    pluginCwd;
+    /**
+     * The deployment region for resource context
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/MainBase.html#region | API: MainBase.region}
+     */
+    region;
+    constructor(config) {
+        this.appId = config.appId;
+        this.mode = config.mode;
+        if (config.pluginName !== "") {
+            this.pluginName = config.pluginName;
+        }
+        this.cwd = config.cwd;
+        this.packageCwd = config.packageCwd;
+        this.pluginCwd = config.pluginCwd;
+        this.region = config.region;
+    }
+}
+exports.MainBase = MainBase;
+/**
+ * @hidden
+ */
+class Base extends MainBase {
+    /**
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Base.html | API: Base}
+     */
+    constructor(config) {
+        super(config);
+    }
+}
+exports.Base = Base;
+/**
+ * @hidden
+ * used by logging plugins (does not need events or logging since logging logs its own logs)
+ */
+class BaseWithConfig extends Base {
+    /**
+     * The config of the plugin
+     * @type {PluginConfig}
+     * @readonly
+     */
+    config;
+    constructor(config) {
+        super(config);
+        this.config = config.config;
+    }
+}
+exports.BaseWithConfig = BaseWithConfig;
+/**
+ * @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
+ */
+class BaseWithObservable extends Base {
+    /**
+     * @hidden
+     * Internal ObservableBackend instance for creating Observables.
+     * NOT accessible to plugin code - use Observable instead.
+     */
+    _observable;
+    constructor(config) {
+        super(config);
+        this._observable = new ObservableBackend_1.ObservableBackend(config.mode, config.appId, config.pluginName, config.sbObservable);
+        // Observable backend initialized
+        // Accessible via this.__internalObservable for creating Observables
+    }
+    /**
+     * @hidden
+     * Get internal observable backend for Observable creation.
+     * NOT for direct plugin use.
+     */
+    get __internalObservable() {
+        return this._observable;
+    }
+}
+exports.BaseWithObservable = BaseWithObservable;
+/**
+ * @hidden
+ * Base class with config and internal observable support.
+ * Use Observable for all logging and metrics operations.
+ */
+class BaseWithObservableAndConfig extends BaseWithConfig {
+    /**
+     * @hidden
+     * Internal ObservableBackend instance for creating Observables.
+     */
+    _observable;
+    constructor(config) {
+        super(config);
+        this._observable = new ObservableBackend_1.ObservableBackend(config.mode, config.appId, config.pluginName, config.sbObservable);
+        // Observable backend initialized
+    }
+    /**
+     * @hidden
+     * Get internal observable backend for Observable creation.
+     */
+    get __internalObservable() {
+        return this._observable;
+    }
+}
+exports.BaseWithObservableAndConfig = BaseWithObservableAndConfig;
+/**
+ * @hidden
+ */
+exports.NS_PER_SEC = 1e9;
+/**
+ * @hidden
+ */
+exports.MS_PER_NS = 1e-6;
+//# sourceMappingURL=base.js.map

package/lib/base/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/base/base.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAKH,2DAAwD;AAuBxD;;GAEG;AACH,MAAsB,QAAQ;IAC5B;;;;;OAKG;IACa,KAAK,GAAW,KAAK,CAAC;IAEtC;;;;;;;;OAQG;IACa,IAAI,GAAe,aAAa,CAAC;IACjD;;;OAGG;IACa,GAAG,CAAS;IAC5B;;;OAGG;IACa,UAAU,CAAS;IACnC;;;OAGG;IACa,SAAS,CAAS;IAQlC;;;OAGG;IACa,MAAM,CAAU;IAEhC,YAAY,MAAsB;QAChC,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACxB,IAAI,MAAM,CAAC,UAAU,KAAK,EAAE,EAAE,CAAC;YAC7B,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;QACtC,CAAC;QACD,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;QACtB,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;QACpC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QAClC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC9B,CAAC;CAUF;AAnED,4BAmEC;AAED;;GAEG;AACH,MAAsB,IACpB,SAAQ,QAAQ;IAChB;;OAEG;IACH,YAAY,MAAsB;QAChC,KAAK,CAAC,MAAM,CAAC,CAAC;IAChB,CAAC;CA6DF;AApED,oBAoEC;AAkCD;;;GAGG;AACH,MAAsB,cAGpB,SAAQ,IAAI;IACZ;;;;OAIG;IACa,MAAM,CAA2C;IAEjE,YAAY,MAA8C;QACxD,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAA6D,CAAC;IACrF,CAAC;CACF;AAfD,wCAeC;AAWD;;;;;;;;;;;GAWG;AACH,MAAsB,kBACpB,SAAQ,IAAI;IACZ;;;;OAIG;IACK,WAAW,CAAoB;IAEvC,YAAY,MAAgC;QAC1C,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,WAAW,GAAG,IAAI,qCAAiB,CACtC,MAAM,CAAC,IAAI,EACX,MAAM,CAAC,KAAK,EACZ,MAAM,CAAC,UAAU,EACjB,MAAM,CAAC,YAAY,CACpB,CAAC;QAEF,iCAAiC;QACjC,oEAAoE;IACtE,CAAC;IAED;;;;OAIG;IACH,IAAc,oBAAoB;QAChC,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;CACF;AA9BD,gDA8BC;AAYD;;;;GAIG;AACH,MAAsB,2BAGpB,SAAQ,cAAgC;IACxC;;;OAGG;IACK,WAAW,CAAoB;IAEvC,YAAY,MAA2D;QACrE,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,WAAW,GAAG,IAAI,qCAAiB,CACtC,MAAM,CAAC,IAAI,EACX,MAAM,CAAC,KAAK,EACZ,MAAM,CAAC,UAAU,EACjB,MAAM,CAAC,YAAY,CACpB,CAAC;QAEF,iCAAiC;IACnC,CAAC;IAED;;;OAGG;IACH,IAAc,oBAAoB;QAChC,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;CACF;AA7BD,kEA6BC;AAED;;GAEG;AACU,QAAA,UAAU,GAAG,GAAG,CAAC;AAC9B;;GAEG;AACU,QAAA,SAAS,GAAG,IAAI,CAAC"}

package/lib/base/errorMessages.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 { DTrace, LogMeta, ParamsFromString } from "../interfaces";
+/**
+ * @hidden
+ */
+export type ErrorLogMetaDefinition<T extends string> = {
+    trace: DTrace;
+    message: T;
+    meta: LogMeta<T>;
+};
+export type ErrorLogMeta<T extends string> = ParamsFromString<T> extends never ? [undefined?] : [meta: LogMeta<T>];
+/**
+ * BSBError is a custom error class that allows for better error handling and logging
+ *
+ * @group Errors
+ * @category Tools
+ * @param message - The message to log
+ * @param meta - Additional information to log with the message
+ */
+/**
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBError.html | API: BSBError}
+ */
+export declare class BSBError<T extends string> extends Error {
+    constructor(trace: DTrace, message: T, ...meta: ErrorLogMeta<T>);
+    raw: ErrorLogMetaDefinition<string> | null;
+    toString(): string;
+}
+/**
+ * @hidden
+ */
+export declare function BSB_ERROR_METHOD_NOT_IMPLEMENTED(className: string, method: string): BSBError<"Method not implemented: {class}.{method}">;

package/lib/base/errorMessages.js

@@ -0,0 +1,70 @@
+"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.BSBError = void 0;
+exports.BSB_ERROR_METHOD_NOT_IMPLEMENTED = BSB_ERROR_METHOD_NOT_IMPLEMENTED;
+const interfaces_1 = require("../interfaces");
+const logFormatter_1 = require("./logFormatter");
+/**
+ * BSBError is a custom error class that allows for better error handling and logging
+ *
+ * @group Errors
+ * @category Tools
+ * @param message - The message to log
+ * @param meta - Additional information to log with the message
+ */
+/**
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBError.html | API: BSBError}
+ */
+class BSBError extends Error {
+    constructor(trace, message, ...meta) {
+        const formatter = new logFormatter_1.LogFormatter();
+        super(formatter.formatLog(trace, message, ...meta));
+        this.name = "BSBError-" + message;
+        this.raw = {
+            trace,
+            message,
+            meta: meta,
+        };
+    }
+    raw = null;
+    toString() {
+        return this.message;
+    }
+}
+exports.BSBError = BSBError;
+/**
+ * @hidden
+ */
+function BSB_ERROR_METHOD_NOT_IMPLEMENTED(className, method) {
+    return new BSBError((0, interfaces_1.createFakeDTrace)('base/errorMessages', 'BSB_ERROR_METHOD_NOT_IMPLEMENTED'), "Method not implemented: {class}.{method}", {
+        class: className,
+        method: method,
+    });
+}
+//# sourceMappingURL=errorMessages.js.map

package/lib/base/errorMessages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorMessages.js","sourceRoot":"","sources":["../../src/base/errorMessages.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAuDH,4EAYC;AAjED,8CAAoF;AACpF,iDAA8C;AAc9C;;;;;;;GAOG;AACH;;GAEG;AACH,MAAa,QACX,SAAQ,KAAK;IACb,YACE,KAAa,EACb,OAAU,EACV,GAAG,IAAqB;QAExB,MAAM,SAAS,GAAG,IAAI,2BAAY,EAAE,CAAC;QACrC,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;QACpD,IAAI,CAAC,IAAI,GAAG,WAAW,GAAG,OAAO,CAAC;QAClC,IAAI,CAAC,GAAG,GAAG;YACT,KAAK;YACL,OAAO;YACP,IAAI,EAAE,IAAI;SACX,CAAC;IACJ,CAAC;IAEM,GAAG,GAA0C,IAAI,CAAC;IAElD,QAAQ;QACb,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;CACF;AAtBD,4BAsBC;AAED;;GAEG;AACH,SAAgB,gCAAgC,CAC9C,SAAiB,EACjB,MAAc;IAEd,OAAO,IAAI,QAAQ,CACjB,IAAA,6BAAgB,EAAC,oBAAoB,EAAE,kCAAkC,CAAC,EAC1E,0CAA0C,EAC1C;QACE,KAAK,EAAE,SAAS;QAChB,MAAM,EAAE,MAAM;KACf,CACF,CAAC;AACJ,CAAC"}

package/lib/base/factory.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 { BSBOptions, ResolvedBSBOptions, SimpleBSBOptions, BSBPreset } from "../interfaces";
+/**
+ * Resolves BSB options with defaults
+ *
+ * @param options - User provided options
+ * @returns Resolved options with all defaults applied
+ *
+ * @group Main
+ * @category Factory
+ */
+export declare function resolveBSBOptions(options?: BSBOptions): ResolvedBSBOptions;
+/**
+ * Creates BSBOptions from simple configuration
+ *
+ * @param simple - Simple configuration options
+ * @returns BSBOptions for ServiceBase
+ *
+ * @group Main
+ * @category Factory
+ */
+export declare function fromSimpleOptions(simple?: SimpleBSBOptions): BSBOptions;
+/**
+ * Creates BSBOptions from preset configuration
+ *
+ * @param preset - Preset type
+ * @param overrides - Additional options to override preset defaults
+ * @returns BSBOptions for ServiceBase
+ *
+ * @group Main
+ * @category Factory
+ */
+export declare function fromPreset(preset: BSBPreset, overrides?: Partial<BSBOptions>): BSBOptions;

package/lib/base/factory.js

@@ -0,0 +1,167 @@
+"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.resolveBSBOptions = resolveBSBOptions;
+exports.fromSimpleOptions = fromSimpleOptions;
+exports.fromPreset = fromPreset;
+const uuid_1 = require("uuid");
+const node_os_1 = require("node:os");
+const interfaces_1 = require("../interfaces");
+const config_1 = require("../serviceBase/config");
+const plugins_1 = require("../serviceBase/plugins");
+const observable_1 = require("../serviceBase/observable");
+const events_1 = require("../serviceBase/events");
+const services_1 = require("../serviceBase/services");
+/**
+ * Resolves BSB options with defaults
+ *
+ * @param options - User provided options
+ * @returns Resolved options with all defaults applied
+ *
+ * @group Main
+ * @category Factory
+ */
+function resolveBSBOptions(options = {}) {
+    const { debug = true, live = false, cwd = process.cwd(), appId, region, config = config_1.SBConfig, plugins = plugins_1.SBPlugins, observable = observable_1.SBObservable, events = events_1.SBEvents, services = services_1.SBServices } = options;
+    // Determine debug mode
+    let mode;
+    if (live === false) {
+        mode = "development";
+    }
+    else if (debug === true) {
+        mode = "production-debug";
+    }
+    else {
+        mode = "production";
+    }
+    // Generate app ID if not provided
+    let resolvedAppId;
+    if (appId) {
+        resolvedAppId = appId;
+    }
+    else if (typeof process.env.BSB_APP_ID === "string" && process.env.BSB_APP_ID.length > 2) {
+        resolvedAppId = process.env.BSB_APP_ID;
+    }
+    else {
+        resolvedAppId = `${(0, node_os_1.hostname)()}-${(0, uuid_1.v7)()}`;
+    }
+    // Resolve region from option → env → undefined
+    let resolvedRegion;
+    if (region) {
+        resolvedRegion = region;
+    }
+    else if (typeof process.env.BSB_REGION === "string" && process.env.BSB_REGION.length > 0) {
+        resolvedRegion = process.env.BSB_REGION;
+    }
+    else {
+        resolvedRegion = undefined;
+    }
+    return {
+        debug,
+        live,
+        cwd,
+        appId: resolvedAppId,
+        region: resolvedRegion,
+        mode,
+        config,
+        plugins,
+        observable,
+        events,
+        services
+    };
+}
+/**
+ * Creates BSBOptions from simple configuration
+ *
+ * @param simple - Simple configuration options
+ * @returns BSBOptions for ServiceBase
+ *
+ * @group Main
+ * @category Factory
+ */
+function fromSimpleOptions(simple = {}) {
+    const { cwd = process.cwd(), debug = process.env.NODE_ENV !== "production" } = simple;
+    // TODO: Handle config file loading and plugin list processing
+    // This would need integration with the config system
+    return {
+        debug,
+        cwd,
+        live: process.env.NODE_ENV === "production"
+    };
+}
+/**
+ * Creates BSBOptions from preset configuration
+ *
+ * @param preset - Preset type
+ * @param overrides - Additional options to override preset defaults
+ * @returns BSBOptions for ServiceBase
+ *
+ * @group Main
+ * @category Factory
+ */
+function fromPreset(preset, overrides = {}) {
+    let baseOptions;
+    switch (preset) {
+        case interfaces_1.BSBPreset.MINIMAL:
+            baseOptions = {
+                debug: false,
+                live: true,
+                cwd: process.cwd()
+            };
+            break;
+        case interfaces_1.BSBPreset.DEVELOPMENT:
+            baseOptions = {
+                debug: true,
+                live: false,
+                cwd: process.cwd()
+            };
+            break;
+        case interfaces_1.BSBPreset.PRODUCTION:
+            baseOptions = {
+                debug: false,
+                live: true,
+                cwd: process.cwd()
+            };
+            break;
+        case interfaces_1.BSBPreset.TESTING:
+            baseOptions = {
+                debug: true,
+                live: false,
+                cwd: process.cwd()
+                // TODO: Add mock implementations for testing
+            };
+            break;
+        default:
+            throw new Error(`Unknown preset: ${preset}`);
+    }
+    return {
+        ...baseOptions,
+        ...overrides
+    };
+}
+//# sourceMappingURL=factory.js.map

package/lib/base/factory.js.map

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

package/lib/base/functions.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 { DTrace } from '../interfaces/metrics';
+import { z } from "zod";
+type SmartFunctionCallFunc = {
+    [Symbol.toStringTag]?: string;
+    (...args: any[]): any;
+};
+/**
+ * initializes a function call and calls it with context but shows as the function type (async/sync)
+ * @group Functions
+ * @category Tools
+ * @param context - the context to call the function with
+ * @param input - the function to call
+ * @param params - the parameters to pass to the function
+ * @returns Async/Sync called function return type or immediately if the input is not a function
+ * @throws BSBError context is not an object
+ *
+ * @example
+ * ```ts
+ * const myFunc = async (a: string, b: number) => {
+ *   console.log("called with " + a + " and " + b);
+ * };
+ * console.log("done with " + (await SmartFunctionCallThroughAsync(this, myFunc, "a", 5)));
+ * ```
+ * @example
+ * ```ts
+ * const myFunc = (a: string, b: number) => {
+ *   console.log("called with " + a + " and " + b);
+ * };
+ * console.log("done with " + SmartFunctionCallThroughAsync(this, myFunc, "a", 5));
+ * ```
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/functions/SmartFunctionCallThroughAsync.html | API: SmartFunctionCallThroughAsync}
+ */
+export declare function SmartFunctionCallThroughAsync<T extends SmartFunctionCallFunc>(trace: DTrace, context: any, input: T | undefined, ...params: Parameters<T>): Promise<ReturnType<T> | void> | ReturnType<T> | void;
+/**
+ * Initializes a function call and calls it with context but shows as the function type (async)
+ * @group Functions
+ * @category Tools
+ * @param trace - the trace to use
+ * @param context - the context to call the function with
+ * @param input - the function to call
+ * @param params - the parameters to pass to the function
+ * @returns Async called function return type or immediately if the input is not a function
+ * @throws BSBError context is not an object
+ *
+ * @example
+ * ```ts
+ * const myFunc = async (a: string, b: number) => {
+ *   console.log("called with " + a + " and " + b);
+ * };
+ * console.log("done with " + await SmartFunctionCallAsync(this, myFunc, "a", 5));
+ * ```
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/functions/SmartFunctionCallAsync.html | API: SmartFunctionCallAsync}
+ */
+export declare function SmartFunctionCallAsync<T extends SmartFunctionCallFunc>(context: any, input: T | undefined, ...params: Parameters<T>): Promise<ReturnType<T> | void>;
+/**
+ * initializes a function call and calls it with context but shows as the function type (sync)
+ * @group Functions
+ * @category Tools
+ * @param context
+ * @param input
+ * @param params
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/functions/SmartFunctionCallSync.html | API: SmartFunctionCallSync}
+ */
+export declare function SmartFunctionCallSync<T extends SmartFunctionCallFunc>(context: any, input: T | undefined, ...params: Parameters<T>): ReturnType<T> | void;
+/**
+ * Validated environment properties for the BSB runtime.
+ *
+ * Use {@link getEnvProps} to read and validate the current process env.
+ *
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/modules.html#ENV_PROPS | API: ENV_PROPS}
+ */
+export declare const ENV_PROPS: z.ZodObject<{
+    BSB_PROFILE: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    BSB_CONFIG_FILE: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    APP_DIR: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    BSB_LOGGER_PLUGIN: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    BSB_LOGGER_PLUGIN_PACKAGE: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Parse and validate the current environment against {@link ENV_PROPS}.
+ *
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/functions/getEnvProps.html | API: getEnvProps}
+ */
+export declare function getEnvProps(): {
+    BSB_PROFILE: string;
+    BSB_CONFIG_FILE: string;
+    APP_DIR: string;
+    BSB_LOGGER_PLUGIN: string;
+    BSB_LOGGER_PLUGIN_PACKAGE: string;
+};
+export {};