@devopsplaybook.io/common-utils 1.0.0-beta.5.18ca754

package/dist/src/ConfigBase.d.ts

@@ -0,0 +1,104 @@
+import { ConfigOTelInterface } from "@devopsplaybook.io/otel-utils";
+/**
+ * Configuration field descriptor used by {@link ConfigBase.addConfigField}.
+ */
+export interface ConfigFieldDef {
+    /** Property name on the config instance. */
+    field: string;
+    /** When `true` the value is masked in log output. */
+    sensitive?: boolean;
+}
+/**
+ * Database-specific configuration fields shared by every project that
+ * supports both SQLite and PostgreSQL backends.
+ */
+export interface ConfigDatabaseInterface {
+    DATABASE_TYPE: "sqlite" | "postgres";
+    DATABASE_POSTGRES_HOST: string;
+    DATABASE_POSTGRES_PORT: number;
+    DATABASE_POSTGRES_USER: string;
+    DATABASE_POSTGRES_PASSWORD: string;
+    DATABASE_POSTGRES_DATABASE: string;
+}
+/**
+ * Common server configuration fields shared across projects.
+ */
+export interface ConfigCommonInterface extends ConfigOTelInterface, ConfigDatabaseInterface {
+    CONFIG_FILE: string;
+    API_PORT: number;
+    JWT_VALIDITY_DURATION: number;
+    CORS_POLICY_ORIGIN: string;
+    DATA_DIR: string;
+    JWT_KEY: string;
+    LOG_LEVEL: string;
+}
+/**
+ * Abstract base class for project configuration.
+ *
+ * Implements the three-layer override strategy used across all
+ * devopsplaybook.io server projects:
+ *   1. **Environment variable** (highest priority)
+ *   2. **config.json** file value
+ *   3. **Default** declared on the class property
+ *
+ * Subclasses add project-specific fields and call {@link addConfigField}
+ * inside their constructor so that {@link reload} picks them up.
+ *
+ * @example
+ * ```ts
+ * class MyConfig extends ConfigBase {
+ *   public MY_SETTING = "default";
+ *   constructor() {
+ *     super("my-service");
+ *     this.addConfigField({ field: "MY_SETTING" });
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class ConfigBase implements ConfigCommonInterface {
+    SERVICE_ID: string;
+    VERSION: string;
+    OPENTELEMETRY_COLLECTOR_HTTP_TRACES: string;
+    OPENTELEMETRY_COLLECTOR_HTTP_METRICS: string;
+    OPENTELEMETRY_COLLECTOR_HTTP_LOGS: string;
+    OPENTELEMETRY_COLLECTOR_AWS: boolean;
+    OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS: number;
+    OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS: number;
+    OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER: string;
+    CONFIG_FILE: string;
+    API_PORT: number;
+    JWT_VALIDITY_DURATION: number;
+    CORS_POLICY_ORIGIN: string;
+    DATA_DIR: string;
+    JWT_KEY: string;
+    LOG_LEVEL: string;
+    DATABASE_TYPE: "sqlite" | "postgres";
+    DATABASE_POSTGRES_HOST: string;
+    DATABASE_POSTGRES_PORT: number;
+    DATABASE_POSTGRES_USER: string;
+    DATABASE_POSTGRES_PASSWORD: string;
+    DATABASE_POSTGRES_DATABASE: string;
+    /**
+     * Fields registered by subclasses (or the base) that {@link reload}
+     * should process.  Common / DB / OTel fields are pre-registered.
+     */
+    private _fields;
+    /**
+     * @param serviceId  Unique service identifier (e.g. `"cryptotrader-server"`).
+     * @param configFile Optional path to the JSON config file. Defaults to `"config.json"`.
+     */
+    constructor(serviceId: string, configFile?: string);
+    /**
+     * Register a configuration field so that {@link reload} processes it.
+     * Call this in your subclass constructor for every project-specific field.
+     */
+    addConfigField(def: ConfigFieldDef): void;
+    /**
+     * Load (or reload) configuration from the JSON file and environment variables.
+     * Environment variables always take precedence over file values.
+     *
+     * @param logger  Optional log callback `(message: string) => void`.
+     *                When omitted nothing is logged (useful in tests).
+     */
+    reload(logger?: (message: string) => void): Promise<void>;
+}

package/dist/src/ConfigBase.js

@@ -0,0 +1,201 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigBase = void 0;
+const fse = __importStar(require("fs-extra"));
+const uuid_1 = require("uuid");
+const path_1 = __importDefault(require("path"));
+/**
+ * Abstract base class for project configuration.
+ *
+ * Implements the three-layer override strategy used across all
+ * devopsplaybook.io server projects:
+ *   1. **Environment variable** (highest priority)
+ *   2. **config.json** file value
+ *   3. **Default** declared on the class property
+ *
+ * Subclasses add project-specific fields and call {@link addConfigField}
+ * inside their constructor so that {@link reload} picks them up.
+ *
+ * @example
+ * ```ts
+ * class MyConfig extends ConfigBase {
+ *   public MY_SETTING = "default";
+ *   constructor() {
+ *     super("my-service");
+ *     this.addConfigField({ field: "MY_SETTING" });
+ *   }
+ * }
+ * ```
+ */
+class ConfigBase {
+    /**
+     * @param serviceId  Unique service identifier (e.g. `"cryptotrader-server"`).
+     * @param configFile Optional path to the JSON config file. Defaults to `"config.json"`.
+     */
+    constructor(serviceId, configFile) {
+        this.VERSION = "1";
+        this.OPENTELEMETRY_COLLECTOR_HTTP_TRACES = "";
+        this.OPENTELEMETRY_COLLECTOR_HTTP_METRICS = "";
+        this.OPENTELEMETRY_COLLECTOR_HTTP_LOGS = "";
+        this.OPENTELEMETRY_COLLECTOR_AWS = false;
+        this.OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS = 60;
+        this.OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS = 60;
+        this.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER = "";
+        this.API_PORT = 8080;
+        this.JWT_VALIDITY_DURATION = 3 * 31 * 24 * 3600;
+        this.CORS_POLICY_ORIGIN = "";
+        this.DATA_DIR = process.env.DATA_DIR || "/data";
+        this.JWT_KEY = (0, uuid_1.v4)();
+        this.LOG_LEVEL = "info";
+        // -- Database fields --
+        this.DATABASE_TYPE = "sqlite";
+        this.DATABASE_POSTGRES_HOST = "";
+        this.DATABASE_POSTGRES_PORT = 5432;
+        this.DATABASE_POSTGRES_USER = "";
+        this.DATABASE_POSTGRES_PASSWORD = "";
+        this.DATABASE_POSTGRES_DATABASE = "";
+        /**
+         * Fields registered by subclasses (or the base) that {@link reload}
+         * should process.  Common / DB / OTel fields are pre-registered.
+         */
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this._fields = [];
+        this.SERVICE_ID = serviceId;
+        this.CONFIG_FILE = configFile || process.env.CONFIG_FILE || "config.json";
+        // Auto-detect version from nearest package.json
+        try {
+            const pkg = fse.readJsonSync(path_1.default.resolve(__dirname, "../package.json"));
+            if (pkg && pkg.version) {
+                this.VERSION = pkg.version;
+            }
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        }
+        catch (_e) {
+            // fallback to "1"
+        }
+        // Pre-register base + DB + OTel fields so reload() handles them
+        const baseFields = [
+            { field: "JWT_VALIDITY_DURATION" },
+            { field: "CORS_POLICY_ORIGIN" },
+            { field: "DATA_DIR" },
+            { field: "JWT_KEY", sensitive: true },
+            { field: "LOG_LEVEL" },
+            { field: "DATABASE_TYPE" },
+            { field: "DATABASE_POSTGRES_HOST" },
+            { field: "DATABASE_POSTGRES_PORT" },
+            { field: "DATABASE_POSTGRES_USER" },
+            { field: "DATABASE_POSTGRES_PASSWORD", sensitive: true },
+            { field: "DATABASE_POSTGRES_DATABASE" },
+            { field: "OPENTELEMETRY_COLLECTOR_HTTP_TRACES" },
+            { field: "OPENTELEMETRY_COLLECTOR_HTTP_METRICS" },
+            { field: "OPENTELEMETRY_COLLECTOR_HTTP_LOGS" },
+            { field: "OPENTELEMETRY_COLLECTOR_AWS" },
+            {
+                field: "OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS",
+            },
+            {
+                field: "OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS",
+            },
+            {
+                field: "OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER",
+                sensitive: true,
+            },
+        ];
+        for (const f of baseFields) {
+            this.addConfigField(f);
+        }
+    }
+    /**
+     * Register a configuration field so that {@link reload} processes it.
+     * Call this in your subclass constructor for every project-specific field.
+     */
+    addConfigField(def) {
+        var _a;
+        this._fields.push({
+            field: def.field,
+            sensitive: (_a = def.sensitive) !== null && _a !== void 0 ? _a : false,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            defaultValue: this[def.field],
+        });
+    }
+    /**
+     * Load (or reload) configuration from the JSON file and environment variables.
+     * Environment variables always take precedence over file values.
+     *
+     * @param logger  Optional log callback `(message: string) => void`.
+     *                When omitted nothing is logged (useful in tests).
+     */
+    async reload(logger) {
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        const log = logger !== null && logger !== void 0 ? logger : (() => { });
+        let content = {};
+        try {
+            content = await fse.readJson(this.CONFIG_FILE);
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        }
+        catch (_e) {
+            // config file is optional – fall back to env + defaults
+        }
+        log(`Configuration Value: CONFIG_FILE: ${this.CONFIG_FILE}`);
+        log(`Configuration Value: SERVICE_ID: ${this.SERVICE_ID}`);
+        log(`Configuration Value: VERSION: ${this.VERSION}`);
+        for (const { field, sensitive } of this._fields) {
+            let from = "defaults";
+            if (process.env[field] !== undefined) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                this[field] = process.env[field];
+                from = "environment";
+            }
+            else if (content[field] !== undefined) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                this[field] = content[field];
+                from = "config";
+            }
+            if (sensitive) {
+                log(`Configuration Value: ${field}: ******************** (from ${from})`);
+            }
+            else {
+                log(
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                `Configuration Value: ${field}: ${this[field]} (from ${from})`);
+            }
+        }
+    }
+}
+exports.ConfigBase = ConfigBase;

package/dist/src/DbUtils.d.ts

@@ -0,0 +1,50 @@
+import { Span } from "@opentelemetry/sdk-trace-base";
+import { StandardTracer, StandardLogger } from "@devopsplaybook.io/otel-utils";
+import * as SqlDbUtils from "./SqlDbUtils";
+import * as PostgresDbUtils from "./PostgresDbUtils";
+/**
+ * Configuration subset required by the unified DB facade.
+ */
+export interface DbUtilsConfig extends SqlDbUtils.SqlDbConfig, PostgresDbUtils.PostgresDbConfig {
+    DATABASE_TYPE: "sqlite" | "postgres";
+}
+/**
+ * Injects the OTel tracer and logger instances used by the DB layer.
+ * Must be called once at startup, before {@link DbUtilsInit}.
+ */
+export declare function DbUtilsSetOTel(tracer: StandardTracer, logger: StandardLogger): void;
+/**
+ * Initialise the database layer.
+ *
+ * Dispatches to the SQLite or Postgres backend depending on
+ * `config.DATABASE_TYPE` and runs pending migration files from `sqlDir`.
+ *
+ * @param context  Parent OTel span.
+ * @param config   Server configuration.
+ * @param sqlDir   Absolute path to the directory containing SQL migration files.
+ */
+export declare function DbUtilsInit(context: Span, config: DbUtilsConfig, sqlDir: string): Promise<void>;
+/**
+ * Returns the native database handle.
+ * - SQLite: `better-sqlite3` `Database` instance
+ * - Postgres: `pg` `Pool` instance
+ */
+export declare function DbUtilsGetDatabase(): any;
+/** Convert SQLite `?` placeholders to PostgreSQL `$1, $2, ...` numbering. */
+export declare function convertToPostgresPlaceholders(sql: string): string;
+/**
+ * Execute a write SQL statement with OTel tracing.
+ * Automatically converts `?` placeholders to `$N` when using Postgres.
+ *
+ * @returns Number of rows changed.
+ */
+export declare function DbUtilsExecSQL(context: Span, sql: string, params?: unknown[]): number | Promise<number>;
+/**
+ * Execute a read SQL query with OTel tracing.
+ * Automatically converts `?` placeholders to `$N` when using Postgres.
+ *
+ * @returns Array of row objects.
+ */
+export declare function DbUtilsQuerySQL(context: Span, sql: string, params?: unknown[], debug?: boolean): any[] | Promise<any[]>;
+/** Returns the active database type (`"sqlite"` or `"postgres"`). */
+export declare function DbUtilsGetType(): "sqlite" | "postgres";

package/dist/src/DbUtils.js

@@ -0,0 +1,117 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DbUtilsSetOTel = DbUtilsSetOTel;
+exports.DbUtilsInit = DbUtilsInit;
+exports.DbUtilsGetDatabase = DbUtilsGetDatabase;
+exports.convertToPostgresPlaceholders = convertToPostgresPlaceholders;
+exports.DbUtilsExecSQL = DbUtilsExecSQL;
+exports.DbUtilsQuerySQL = DbUtilsQuerySQL;
+exports.DbUtilsGetType = DbUtilsGetType;
+const SqlDbUtils = __importStar(require("./SqlDbUtils"));
+const PostgresDbUtils = __importStar(require("./PostgresDbUtils"));
+let databaseType = "sqlite";
+/**
+ * Injects the OTel tracer and logger instances used by the DB layer.
+ * Must be called once at startup, before {@link DbUtilsInit}.
+ */
+function DbUtilsSetOTel(tracer, logger) {
+    SqlDbUtils.SqlDbUtilsSetOTel(tracer, logger);
+    PostgresDbUtils.PostgresDbUtilsSetOTel(tracer, logger);
+}
+/**
+ * Initialise the database layer.
+ *
+ * Dispatches to the SQLite or Postgres backend depending on
+ * `config.DATABASE_TYPE` and runs pending migration files from `sqlDir`.
+ *
+ * @param context  Parent OTel span.
+ * @param config   Server configuration.
+ * @param sqlDir   Absolute path to the directory containing SQL migration files.
+ */
+async function DbUtilsInit(context, config, sqlDir) {
+    databaseType = config.DATABASE_TYPE;
+    if (databaseType === "postgres") {
+        await PostgresDbUtils.PostgresDbUtilsInit(context, config, sqlDir);
+    }
+    else {
+        await SqlDbUtils.SqlDbUtilsInit(context, config, sqlDir);
+    }
+}
+/**
+ * Returns the native database handle.
+ * - SQLite: `better-sqlite3` `Database` instance
+ * - Postgres: `pg` `Pool` instance
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function DbUtilsGetDatabase() {
+    if (databaseType === "postgres") {
+        return PostgresDbUtils.PostgresDbUtilsGetPool();
+    }
+    return SqlDbUtils.SqlDbUtilsGetDatabase();
+}
+/** Convert SQLite `?` placeholders to PostgreSQL `$1, $2, ...` numbering. */
+function convertToPostgresPlaceholders(sql) {
+    let paramIndex = 1;
+    return sql.replace(/\?/g, () => `$${paramIndex++}`);
+}
+/**
+ * Execute a write SQL statement with OTel tracing.
+ * Automatically converts `?` placeholders to `$N` when using Postgres.
+ *
+ * @returns Number of rows changed.
+ */
+function DbUtilsExecSQL(context, sql, params = []) {
+    if (databaseType === "postgres") {
+        return PostgresDbUtils.PostgresDbUtilsExecSQL(context, convertToPostgresPlaceholders(sql), params);
+    }
+    return SqlDbUtils.SqlDbUtilsExecSQL(context, sql, params);
+}
+/**
+ * Execute a read SQL query with OTel tracing.
+ * Automatically converts `?` placeholders to `$N` when using Postgres.
+ *
+ * @returns Array of row objects.
+ */
+function DbUtilsQuerySQL(context, sql, params = [], debug = false) {
+    if (databaseType === "postgres") {
+        return PostgresDbUtils.PostgresDbUtilsQuerySQL(context, convertToPostgresPlaceholders(sql), params, debug);
+    }
+    return SqlDbUtils.SqlDbUtilsQuerySQL(context, sql, params, debug);
+}
+/** Returns the active database type (`"sqlite"` or `"postgres"`). */
+function DbUtilsGetType() {
+    return databaseType;
+}

package/dist/src/DbUtilsNoTelemetry.d.ts

@@ -0,0 +1,27 @@
+import { StandardLogger } from "@devopsplaybook.io/otel-utils";
+/**
+ * Injects the OTel logger instance used by no-telemetry DB operations.
+ * Must be called once at startup.
+ */
+export declare function DbUtilsNoTelemetrySetLogger(loggerIn: StandardLogger): void;
+/**
+ * Execute a multi-row INSERT with a flat parameter array.
+ * Builds: INSERT INTO <tableCols> VALUES (?,?...),(?,?...),...
+ *
+ * @returns Number of rows inserted.
+ */
+export declare function DbUtilsNoTelemetryBatchInsert(tableCols: string, numCols: number, rows: any[][]): number | Promise<number>;
+/**
+ * Execute a write SQL statement **without** creating an OTel span.
+ * Use this on high-throughput paths where span overhead matters.
+ *
+ * @returns Number of rows changed.
+ */
+export declare function DbUtilsNoTelemetryExecSQL(sql: string, params?: unknown[]): number | Promise<number>;
+/**
+ * Execute a read SQL query **without** creating an OTel span.
+ * Use this on high-throughput paths where span overhead matters.
+ *
+ * @returns Array of row objects.
+ */
+export declare function DbUtilsNoTelemetryQuerySQL(sql: string, params?: unknown[], debug?: boolean): any[] | Promise<any[]>;

package/dist/src/DbUtilsNoTelemetry.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DbUtilsNoTelemetrySetLogger = DbUtilsNoTelemetrySetLogger;
+exports.DbUtilsNoTelemetryBatchInsert = DbUtilsNoTelemetryBatchInsert;
+exports.DbUtilsNoTelemetryExecSQL = DbUtilsNoTelemetryExecSQL;
+exports.DbUtilsNoTelemetryQuerySQL = DbUtilsNoTelemetryQuerySQL;
+const DbUtils_1 = require("./DbUtils");
+let logger;
+/**
+ * Injects the OTel logger instance used by no-telemetry DB operations.
+ * Must be called once at startup.
+ */
+function DbUtilsNoTelemetrySetLogger(loggerIn) {
+    logger = loggerIn.createModuleLogger("DbUtilsNoTelemetry");
+}
+/**
+ * Execute a multi-row INSERT with a flat parameter array.
+ * Builds: INSERT INTO <tableCols> VALUES (?,?...),(?,?...),...
+ *
+ * @returns Number of rows inserted.
+ */
+function DbUtilsNoTelemetryBatchInsert(tableCols, numCols, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+rows) {
+    if (rows.length === 0)
+        return 0;
+    const rowSQL = `(${Array.from({ length: numCols }, () => "?").join(",")})`;
+    const multiValues = Array.from({ length: rows.length }, () => rowSQL).join(",");
+    const sql = `INSERT ${tableCols} VALUES ${multiValues}`;
+    return DbUtilsNoTelemetryExecSQL(sql, rows.flat());
+}
+/**
+ * Execute a write SQL statement **without** creating an OTel span.
+ * Use this on high-throughput paths where span overhead matters.
+ *
+ * @returns Number of rows changed.
+ */
+function DbUtilsNoTelemetryExecSQL(sql, params = []) {
+    const dbType = (0, DbUtils_1.DbUtilsGetType)();
+    if (dbType === "postgres") {
+        const pgSql = (0, DbUtils_1.convertToPostgresPlaceholders)(sql);
+        return new Promise((resolve, reject) => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (0, DbUtils_1.DbUtilsGetDatabase)().query(pgSql, params, (error, result) => {
+                if (error) {
+                    logger.error(`SQL INSERT ERROR: ${sql.substring(0, 200)}`, error);
+                    reject(error);
+                }
+                else {
+                    resolve(result.rowCount || 0);
+                }
+            });
+        });
+    }
+    // SQLite (better-sqlite3) – synchronous
+    const stmt = (0, DbUtils_1.DbUtilsGetDatabase)().prepare(sql);
+    const result = stmt.run(params);
+    return result.changes;
+}
+/**
+ * Execute a read SQL query **without** creating an OTel span.
+ * Use this on high-throughput paths where span overhead matters.
+ *
+ * @returns Array of row objects.
+ */
+function DbUtilsNoTelemetryQuerySQL(sql, params = [], debug = false) {
+    if (debug) {
+        console.log(sql);
+    }
+    const dbType = (0, DbUtils_1.DbUtilsGetType)();
+    if (dbType === "postgres") {
+        const pgSql = (0, DbUtils_1.convertToPostgresPlaceholders)(sql);
+        return new Promise((resolve, reject) => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (0, DbUtils_1.DbUtilsGetDatabase)().query(pgSql, params, (error, result) => {
+                if (error) {
+                    logger.error(`SQL ERROR: ${sql}`, error);
+                    reject(error);
+                }
+                else {
+                    resolve(result.rows);
+                }
+            });
+        });
+    }
+    // SQLite (better-sqlite3) – synchronous
+    const stmt = (0, DbUtils_1.DbUtilsGetDatabase)().prepare(sql);
+    return stmt.all(params);
+}

package/dist/src/OTelContext.d.ts

@@ -0,0 +1,35 @@
+import { StandardLogger, StandardMeter, StandardTracer } from "@devopsplaybook.io/otel-utils";
+import { Span } from "@opentelemetry/sdk-trace-base";
+/**
+ * Result of {@link createOTelContext}.
+ * Holds module-level singletons for the OpenTelemetry tracer, meter and logger
+ * used throughout a server process.
+ */
+export interface OTelContext {
+    OTelTracer: () => StandardTracer;
+    OTelSetTracer: (tracer: StandardTracer) => void;
+    OTelMeter: () => StandardMeter;
+    OTelSetMeter: (meter: StandardMeter) => void;
+    OTelLogger: () => StandardLogger;
+    /**
+     * Retrieves the span previously attached to a request object.
+     * Equivalent to `req.tracerSpanApi`.
+     */
+    OTelRequestSpan: (req: any) => Span | undefined;
+}
+/**
+ * Creates an isolated OTel context (tracer / meter / logger singletons).
+ *
+ * Each server process should call this once at startup and pass the returned
+ * object to modules that need telemetry access.  This avoids polluting the
+ * global module scope and makes unit-testing straightforward.
+ *
+ * @example
+ * ```ts
+ * const otel = createOTelContext();
+ * otel.OTelSetTracer(new StandardTracer(config));
+ * otel.OTelSetMeter(new StandardMeter(config));
+ * otel.OTelLogger().initOTel(config);
+ * ```
+ */
+export declare function createOTelContext(): OTelContext;

package/dist/src/OTelContext.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOTelContext = createOTelContext;
+const otel_utils_1 = require("@devopsplaybook.io/otel-utils");
+/**
+ * Creates an isolated OTel context (tracer / meter / logger singletons).
+ *
+ * Each server process should call this once at startup and pass the returned
+ * object to modules that need telemetry access.  This avoids polluting the
+ * global module scope and makes unit-testing straightforward.
+ *
+ * @example
+ * ```ts
+ * const otel = createOTelContext();
+ * otel.OTelSetTracer(new StandardTracer(config));
+ * otel.OTelSetMeter(new StandardMeter(config));
+ * otel.OTelLogger().initOTel(config);
+ * ```
+ */
+function createOTelContext() {
+    let tracer;
+    let meter;
+    let logger;
+    return {
+        OTelTracer: () => tracer,
+        OTelSetTracer: (t) => {
+            tracer = t;
+        },
+        OTelMeter: () => meter,
+        OTelSetMeter: (m) => {
+            meter = m;
+        },
+        OTelLogger: () => {
+            if (!logger) {
+                logger = new otel_utils_1.StandardLogger();
+            }
+            return logger;
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        OTelRequestSpan: (req) => req === null || req === void 0 ? void 0 : req.tracerSpanApi,
+    };
+}