@devopsplaybook.io/common-utils 1.0.0-beta.5.9c5ecde

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,
+    };
+}

package/dist/src/PostgresDbUtils.d.ts

@@ -0,0 +1,52 @@
+import { Pool } from "pg";
+import { Span } from "@opentelemetry/sdk-trace-base";
+import { StandardTracer, StandardLogger } from "@devopsplaybook.io/otel-utils";
+/**
+ * Configuration subset required by the Postgres module.
+ */
+export interface PostgresDbConfig {
+    DATABASE_POSTGRES_HOST: string;
+    DATABASE_POSTGRES_PORT: number;
+    DATABASE_POSTGRES_USER: string;
+    DATABASE_POSTGRES_PASSWORD: string;
+    DATABASE_POSTGRES_DATABASE: string;
+}
+/**
+ * Injects the OTel tracer and logger instances used by all Postgres operations.
+ * Must be called once at startup, before {@link PostgresDbUtilsInit}.
+ */
+export declare function PostgresDbUtilsSetOTel(tracerIn: StandardTracer, loggerIn: StandardLogger): void;
+/**
+ * Creates the Postgres connection pool and applies pending migration files
+ * from `sqlDir`.
+ *
+ * Migration files must follow the naming convention `init-NNNN.sql` and are
+ * applied in lexicographic order.  A `metadata` table tracks which migrations
+ * have already been applied so they are idempotent.
+ *
+ * @param context  Parent OTel span.
+ * @param config   Configuration with Postgres connection fields.
+ * @param sqlDir   Absolute path to the directory containing SQL migration files
+ *                 written for Postgres (with `$1,$2...` placeholders).
+ *                 If migrations are SQLite-first, use `convertToPostgresPlaceholders`
+ *                 before passing them.
+ */
+export declare function PostgresDbUtilsInit(context: Span, config: PostgresDbConfig, sqlDir: string): Promise<void>;
+/** Returns the underlying `pg.Pool` instance. */
+export declare function PostgresDbUtilsGetPool(): Pool;
+/**
+ * Execute a write SQL statement with OTel tracing.
+ * @returns Number of rows changed.
+ */
+export declare function PostgresDbUtilsExecSQL(context: Span, sql: string, params?: unknown[]): Promise<number>;
+/** Execute an entire SQL file (used for migrations). */
+export declare function PostgresDbUtilsExecSQLFile(context: Span, filename: string): Promise<void>;
+/**
+ * Execute a read SQL query with OTel tracing.
+ * @returns Array of row objects.
+ */
+export declare function PostgresDbUtilsQuerySQL(context: Span, sql: string, params?: unknown[], debug?: boolean): Promise<any[]>;
+/** Start a transaction. */
+export declare function PostgresDbUtilsTransactionStart(context: Span): Promise<void>;
+/** Commit a transaction. */
+export declare function PostgresDbUtilsTransactionCommit(context: Span): Promise<void>;

package/dist/src/PostgresDbUtils.js

@@ -0,0 +1,217 @@
+"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.PostgresDbUtilsSetOTel = PostgresDbUtilsSetOTel;
+exports.PostgresDbUtilsInit = PostgresDbUtilsInit;
+exports.PostgresDbUtilsGetPool = PostgresDbUtilsGetPool;
+exports.PostgresDbUtilsExecSQL = PostgresDbUtilsExecSQL;
+exports.PostgresDbUtilsExecSQLFile = PostgresDbUtilsExecSQLFile;
+exports.PostgresDbUtilsQuerySQL = PostgresDbUtilsQuerySQL;
+exports.PostgresDbUtilsTransactionStart = PostgresDbUtilsTransactionStart;
+exports.PostgresDbUtilsTransactionCommit = PostgresDbUtilsTransactionCommit;
+const pg_1 = require("pg");
+const fs = __importStar(require("fs-extra"));
+const api_1 = require("@opentelemetry/api");
+let pool;
+let tracer;
+let logger;
+/**
+ * Injects the OTel tracer and logger instances used by all Postgres operations.
+ * Must be called once at startup, before {@link PostgresDbUtilsInit}.
+ */
+function PostgresDbUtilsSetOTel(tracerIn, loggerIn) {
+    tracer = tracerIn;
+    logger = loggerIn.createModuleLogger("PostgresDbUtils");
+}
+/**
+ * Creates the Postgres connection pool and applies pending migration files
+ * from `sqlDir`.
+ *
+ * Migration files must follow the naming convention `init-NNNN.sql` and are
+ * applied in lexicographic order.  A `metadata` table tracks which migrations
+ * have already been applied so they are idempotent.
+ *
+ * @param context  Parent OTel span.
+ * @param config   Configuration with Postgres connection fields.
+ * @param sqlDir   Absolute path to the directory containing SQL migration files
+ *                 written for Postgres (with `$1,$2...` placeholders).
+ *                 If migrations are SQLite-first, use `convertToPostgresPlaceholders`
+ *                 before passing them.
+ */
+async function PostgresDbUtilsInit(context, config, sqlDir) {
+    const span = tracer.startSpan("PostgresDbUtilsInit", context);
+    pool = new pg_1.Pool({
+        host: config.DATABASE_POSTGRES_HOST,
+        port: config.DATABASE_POSTGRES_PORT || 5432,
+        user: config.DATABASE_POSTGRES_USER,
+        password: config.DATABASE_POSTGRES_PASSWORD,
+        database: config.DATABASE_POSTGRES_DATABASE,
+        max: 20,
+        idleTimeoutMillis: 30000,
+        connectionTimeoutMillis: 10000,
+        keepAlive: true,
+    });
+    pool.on("error", (err) => {
+        logger.error("PostgreSQL pool connection error", err);
+    });
+    await PostgresDbUtilsExecSQLFile(span, `${sqlDir}/init-0000.sql`);
+    const initFiles = (await fs.readdir(sqlDir)).sort();
+    let dbVersionApplied = 0;
+    const dbVersionQuery = await PostgresDbUtilsQuerySQL(span, "SELECT MAX(value) as version FROM metadata WHERE \"type\" = 'db_version'");
+    if (dbVersionQuery.length > 0 && dbVersionQuery[0].version) {
+        dbVersionApplied = Number(dbVersionQuery[0].version);
+    }
+    logger.info(`Current DB Version: ${dbVersionApplied}`, span);
+    for (const initFile of initFiles) {
+        const regex = /init-(\d+).sql/g;
+        const match = regex.exec(initFile);
+        if (match) {
+            const dbVersionInitFile = Number(match[1]);
+            if (dbVersionInitFile > dbVersionApplied) {
+                logger.info(`Loading init file: ${initFile}`, span);
+                await PostgresDbUtilsExecSQLFile(span, `${sqlDir}/${initFile}`);
+                await PostgresDbUtilsQuerySQL(span, 'INSERT INTO metadata ("type", "value", "dateCreated") VALUES ($1, $2, $3)', ["db_version", dbVersionInitFile, new Date().toISOString()]);
+            }
+        }
+    }
+    span.end();
+}
+/** Returns the underlying `pg.Pool` instance. */
+function PostgresDbUtilsGetPool() {
+    return pool;
+}
+/**
+ * Execute a write SQL statement with OTel tracing.
+ * @returns Number of rows changed.
+ */
+function PostgresDbUtilsExecSQL(context, sql, params = []) {
+    const span = tracer.startSpan("PostgresDbUtilsExecSQL", context);
+    return new Promise((resolve, reject) => {
+        pool.query(sql, params, (error, result) => {
+            if (error) {
+                span.setStatus({
+                    code: api_1.SpanStatusCode.ERROR,
+                    message: error.message,
+                });
+                span.end();
+                reject(error);
+            }
+            else {
+                span.addEvent(`Impacted Rows: ${result.rowCount || 0}`);
+                span.end();
+                resolve(result.rowCount || 0);
+            }
+        });
+    });
+}
+/** Execute an entire SQL file (used for migrations). */
+async function PostgresDbUtilsExecSQLFile(context, filename) {
+    const span = tracer.startSpan("PostgresDbUtilsExecSQLFile", context);
+    const sql = (await fs.readFile(filename)).toString();
+    return new Promise((resolve, reject) => {
+        pool.query(sql, (error) => {
+            if (error) {
+                span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
+                span.end();
+                reject(error);
+            }
+            else {
+                span.end();
+                resolve();
+            }
+        });
+    });
+}
+/**
+ * Execute a read SQL query with OTel tracing.
+ * @returns Array of row objects.
+ */
+function PostgresDbUtilsQuerySQL(context, sql, params = [], debug = false) {
+    const span = tracer.startSpan("PostgresDbUtilsQuerySQL", context);
+    if (debug) {
+        console.log(sql);
+    }
+    return new Promise((resolve, reject) => {
+        pool.query(sql, params, (error, result) => {
+            if (error) {
+                span.setStatus({
+                    code: api_1.SpanStatusCode.ERROR,
+                    message: error.message,
+                });
+                logger.error(`SQL ERROR: ${sql}`, error, span);
+                span.end();
+                reject(error);
+            }
+            else {
+                span.end();
+                resolve(result.rows);
+            }
+        });
+    });
+}
+/** Start a transaction. */
+function PostgresDbUtilsTransactionStart(context) {
+    const span = tracer.startSpan("PostgresDbUtilsTransactionStart", context);
+    return new Promise((resolve, reject) => {
+        pool.query("BEGIN", (error) => {
+            if (error) {
+                span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
+                span.end();
+                reject(error);
+            }
+            else {
+                span.end();
+                resolve();
+            }
+        });
+    });
+}
+/** Commit a transaction. */
+function PostgresDbUtilsTransactionCommit(context) {
+    const span = tracer.startSpan("PostgresDbUtilsTransactionCommit", context);
+    return new Promise((resolve, reject) => {
+        pool.query("COMMIT", (error) => {
+            if (error) {
+                span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
+                span.end();
+                reject(error);
+            }
+            else {
+                span.end();
+                resolve();
+            }
+        });
+    });
+}

package/dist/src/SqlDbUtils.d.ts

@@ -0,0 +1,40 @@
+import Database from "better-sqlite3";
+import { Span } from "@opentelemetry/sdk-trace-base";
+import { StandardTracer, StandardLogger } from "@devopsplaybook.io/otel-utils";
+/**
+ * Configuration subset required by the SQLite module.
+ */
+export interface SqlDbConfig {
+    DATA_DIR: string;
+}
+/**
+ * Injects the OTel tracer and logger instances used by all SQL operations.
+ * Must be called once at startup, before {@link SqlDbUtilsInit}.
+ */
+export declare function SqlDbUtilsSetOTel(tracerIn: StandardTracer, loggerIn: StandardLogger): void;
+/**
+ * Opens the SQLite database and applies pending migration files from `sqlDir`.
+ *
+ * Migration files must follow the naming convention `init-NNNN.sql` and are
+ * applied in lexicographic order.  A `metadata` table tracks which migrations
+ * have already been applied so they are idempotent.
+ *
+ * @param context  Parent OTel span.
+ * @param config   Configuration with `DATA_DIR`.
+ * @param sqlDir   Absolute path to the directory containing SQL migration files.
+ */
+export declare function SqlDbUtilsInit(context: Span, config: SqlDbConfig, sqlDir: string): Promise<void>;
+/** Returns the underlying `better-sqlite3` Database instance. */
+export declare function SqlDbUtilsGetDatabase(): Database.Database;
+/**
+ * Execute a write SQL statement with OTel tracing.
+ * @returns Number of rows changed.
+ */
+export declare function SqlDbUtilsExecSQL(context: Span, sql: string, params?: unknown[]): number;
+/** Execute an entire SQL file (used for migrations). */
+export declare function SqlDbUtilsExecSQLFile(context: Span, filename: string): void;
+/**
+ * Execute a read SQL query with OTel tracing.
+ * @returns Array of row objects.
+ */
+export declare function SqlDbUtilsQuerySQL(context: Span, sql: string, params?: unknown[], debug?: boolean): any[];

package/dist/src/SqlDbUtils.js

@@ -0,0 +1,156 @@
+"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.SqlDbUtilsSetOTel = SqlDbUtilsSetOTel;
+exports.SqlDbUtilsInit = SqlDbUtilsInit;
+exports.SqlDbUtilsGetDatabase = SqlDbUtilsGetDatabase;
+exports.SqlDbUtilsExecSQL = SqlDbUtilsExecSQL;
+exports.SqlDbUtilsExecSQLFile = SqlDbUtilsExecSQLFile;
+exports.SqlDbUtilsQuerySQL = SqlDbUtilsQuerySQL;
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const fs = __importStar(require("fs-extra"));
+const api_1 = require("@opentelemetry/api");
+let database;
+let tracer;
+let logger;
+/**
+ * Injects the OTel tracer and logger instances used by all SQL operations.
+ * Must be called once at startup, before {@link SqlDbUtilsInit}.
+ */
+function SqlDbUtilsSetOTel(tracerIn, loggerIn) {
+    tracer = tracerIn;
+    logger = loggerIn.createModuleLogger("SqlDbUtils");
+}
+/**
+ * Opens the SQLite database and applies pending migration files from `sqlDir`.
+ *
+ * Migration files must follow the naming convention `init-NNNN.sql` and are
+ * applied in lexicographic order.  A `metadata` table tracks which migrations
+ * have already been applied so they are idempotent.
+ *
+ * @param context  Parent OTel span.
+ * @param config   Configuration with `DATA_DIR`.
+ * @param sqlDir   Absolute path to the directory containing SQL migration files.
+ */
+async function SqlDbUtilsInit(context, config, sqlDir) {
+    const span = tracer.startSpan("SqlDbUtilsInit", context);
+    await fs.ensureDir(config.DATA_DIR);
+    database = new better_sqlite3_1.default(`${config.DATA_DIR}/database.db`);
+    SqlDbUtilsExecSQLFile(span, `${sqlDir}/init-0000.sql`);
+    const initFiles = (await fs.readdir(sqlDir)).sort();
+    let dbVersionApplied = 0;
+    const rows = SqlDbUtilsQuerySQL(span, "SELECT MAX(value) as maxVersion FROM metadata WHERE type='db_version'");
+    if (rows.length > 0 && rows[0].maxVersion) {
+        dbVersionApplied = Number(rows[0].maxVersion);
+    }
+    logger.info(`Current DB Version: ${dbVersionApplied}`, span);
+    for (const initFile of initFiles) {
+        const regex = /init-(\d+).sql/g;
+        const match = regex.exec(initFile);
+        if (match) {
+            const dbVersionInitFile = Number(match[1]);
+            if (dbVersionInitFile > dbVersionApplied) {
+                logger.info(`Loading init file: ${initFile}`, span);
+                SqlDbUtilsExecSQLFile(span, `${sqlDir}/${initFile}`);
+                SqlDbUtilsExecSQL(span, "INSERT INTO metadata (type, value, dateCreated) VALUES ('db_version',?,?)", [dbVersionInitFile, new Date().toISOString()]);
+            }
+        }
+    }
+    span.end();
+}
+/** Returns the underlying `better-sqlite3` Database instance. */
+function SqlDbUtilsGetDatabase() {
+    return database;
+}
+/**
+ * Execute a write SQL statement with OTel tracing.
+ * @returns Number of rows changed.
+ */
+function SqlDbUtilsExecSQL(context, sql, params = []) {
+    const span = tracer.startSpan("SqlDbUtilsExecSQL", context);
+    try {
+        const stmt = database.prepare(sql);
+        const result = stmt.run(params);
+        span.addEvent(`Impacted Rows: ${result.changes}`);
+        span.end();
+        return result.changes;
+    }
+    catch (error) {
+        const err = error;
+        span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: err.message });
+        span.end();
+        throw error;
+    }
+}
+/** Execute an entire SQL file (used for migrations). */
+function SqlDbUtilsExecSQLFile(context, filename) {
+    const span = tracer.startSpan("SqlDbUtilsExecSQLFile", context);
+    try {
+        const sql = fs.readFileSync(filename).toString();
+        database.exec(sql);
+        span.end();
+    }
+    catch (error) {
+        const err = error;
+        span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: err.message });
+        span.end();
+        throw error;
+    }
+}
+/**
+ * Execute a read SQL query with OTel tracing.
+ * @returns Array of row objects.
+ */
+function SqlDbUtilsQuerySQL(context, sql, params = [], debug = false) {
+    const span = tracer.startSpan("SqlDbUtilsQuerySQL", context);
+    if (debug) {
+        console.log(sql);
+    }
+    try {
+        const stmt = database.prepare(sql);
+        const rows = stmt.all(params);
+        span.end();
+        return rows;
+    }
+    catch (error) {
+        const err = error;
+        span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: err.message });
+        span.end();
+        throw error;
+    }
+}

package/dist/src/SystemCommand.d.ts

@@ -0,0 +1,9 @@
+import * as childProcess from "child_process";
+/**
+ * Execute a shell command and return its stdout.
+ *
+ * @param command  The command string to execute.
+ * @param options  Optional `child_process.exec` options.
+ * @returns Resolves with stdout on success, rejects on error.
+ */
+export declare function SystemCommandExecute(command: string, options?: childProcess.ExecOptions): Promise<string>;