@devopsplaybook.io/common-utils 1.0.0-beta.5.e74e0d9

package/src/DbUtilsNoTelemetry.ts

@@ -0,0 +1,121 @@
+import { StandardLogger, ModuleLogger } from "@devopsplaybook.io/otel-utils";
+import {
+  DbUtilsGetDatabase,
+  DbUtilsGetType,
+  convertToPostgresPlaceholders,
+} from "./DbUtils";
+
+let logger: ModuleLogger;
+
+/**
+ * Injects the OTel logger instance used by no-telemetry DB operations.
+ * Must be called once at startup.
+ */
+export function DbUtilsNoTelemetrySetLogger(loggerIn: StandardLogger): void {
+  logger = loggerIn.createModuleLogger("DbUtilsNoTelemetry");
+}
+
+/**
+ * Execute a multi-row INSERT with a flat parameter array.
+ * Builds: INSERT INTO <tableCols> VALUES (?,?...),(?,?...),...
+ *
+ * @returns Number of rows inserted.
+ */
+export function DbUtilsNoTelemetryBatchInsert(
+  tableCols: string,
+  numCols: number,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  rows: any[][],
+): number | Promise<number> {
+  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.
+ */
+export function DbUtilsNoTelemetryExecSQL(
+  sql: string,
+  params: unknown[] = [],
+): number | Promise<number> {
+  const dbType = DbUtilsGetType();
+  if (dbType === "postgres") {
+    const pgSql = convertToPostgresPlaceholders(sql);
+    return new Promise((resolve, reject) => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (DbUtilsGetDatabase() as any).query(
+        pgSql,
+        params,
+        (error: Error | null, result: { rowCount: number | null }) => {
+          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 = (
+    DbUtilsGetDatabase() as {
+      prepare: (sql: string) => {
+        run: (params: unknown[]) => { changes: number };
+      };
+    }
+  ).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.
+ */
+export function DbUtilsNoTelemetryQuerySQL(
+  sql: string,
+  params: unknown[] = [],
+  debug = false,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): any[] | Promise<any[]> {
+  if (debug) {
+    console.log(sql);
+  }
+  const dbType = DbUtilsGetType();
+  if (dbType === "postgres") {
+    const pgSql = convertToPostgresPlaceholders(sql);
+    return new Promise((resolve, reject) => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (DbUtilsGetDatabase() as any).query(
+        pgSql,
+        params,
+        (error: Error | null, result: { rows: unknown[] }) => {
+          if (error) {
+            logger.error(`SQL ERROR: ${sql}`, error);
+            reject(error);
+          } else {
+            resolve(result.rows);
+          }
+        },
+      );
+    });
+  }
+  // SQLite (better-sqlite3) – synchronous
+  const stmt = (
+    DbUtilsGetDatabase() as {
+      prepare: (sql: string) => { all: (params: unknown[]) => unknown[] };
+    }
+  ).prepare(sql);
+  return stmt.all(params);
+}

package/src/OTelContext.spec.ts

@@ -0,0 +1,58 @@
+import { createOTelContext } from "./OTelContext";
+
+describe("createOTelContext", () => {
+  it("should return an object with all expected methods", () => {
+    const ctx = createOTelContext();
+    expect(typeof ctx.OTelTracer).toBe("function");
+    expect(typeof ctx.OTelSetTracer).toBe("function");
+    expect(typeof ctx.OTelMeter).toBe("function");
+    expect(typeof ctx.OTelSetMeter).toBe("function");
+    expect(typeof ctx.OTelLogger).toBe("function");
+    expect(typeof ctx.OTelRequestSpan).toBe("function");
+  });
+
+  it("should create a StandardLogger lazily", () => {
+    const ctx = createOTelContext();
+    const logger = ctx.OTelLogger();
+    expect(logger).toBeDefined();
+    // Same instance on second call
+    expect(ctx.OTelLogger()).toBe(logger);
+  });
+
+  it("should store and retrieve tracer via setter/getter", () => {
+    const ctx = createOTelContext();
+    const fakeTracer = { id: "tracer-1" } as never;
+    ctx.OTelSetTracer(fakeTracer);
+    expect(ctx.OTelTracer()).toBe(fakeTracer);
+  });
+
+  it("should store and retrieve meter via setter/getter", () => {
+    const ctx = createOTelContext();
+    const fakeMeter = { id: "meter-1" } as never;
+    ctx.OTelSetMeter(fakeMeter);
+    expect(ctx.OTelMeter()).toBe(fakeMeter);
+  });
+
+  it("should isolate contexts from each other", () => {
+    const ctx1 = createOTelContext();
+    const ctx2 = createOTelContext();
+    const fakeTracer1 = { id: "tracer-1" } as never;
+    const fakeTracer2 = { id: "tracer-2" } as never;
+    ctx1.OTelSetTracer(fakeTracer1);
+    ctx2.OTelSetTracer(fakeTracer2);
+    expect(ctx1.OTelTracer()).toBe(fakeTracer1);
+    expect(ctx2.OTelTracer()).toBe(fakeTracer2);
+  });
+
+  it("OTelRequestSpan should return undefined for object without tracerSpanApi", () => {
+    const ctx = createOTelContext();
+    expect(ctx.OTelRequestSpan({})).toBeUndefined();
+  });
+
+  it("OTelRequestSpan should return the span when present", () => {
+    const ctx = createOTelContext();
+    const fakeSpan = { spanId: "123" } as never;
+    const req = { tracerSpanApi: fakeSpan };
+    expect(ctx.OTelRequestSpan(req)).toBe(fakeSpan);
+  });
+});

package/src/OTelContext.ts

@@ -0,0 +1,65 @@
+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`.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  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 function createOTelContext(): OTelContext {
+  let tracer: StandardTracer;
+  let meter: StandardMeter;
+  let logger: StandardLogger;
+
+  return {
+    OTelTracer: () => tracer,
+    OTelSetTracer: (t: StandardTracer) => {
+      tracer = t;
+    },
+    OTelMeter: () => meter,
+    OTelSetMeter: (m: StandardMeter) => {
+      meter = m;
+    },
+    OTelLogger: () => {
+      if (!logger) {
+        logger = new StandardLogger();
+      }
+      return logger;
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    OTelRequestSpan: (req: any) => req?.tracerSpanApi as Span | undefined,
+  };
+}

package/src/PostgresDbUtils.spec.ts

@@ -0,0 +1,155 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+// Mock pg before imports
+const mockQuery = jest.fn();
+jest.mock("pg", () => {
+  return {
+    Pool: jest.fn().mockImplementation(() => ({
+      query: mockQuery,
+      on: jest.fn(),
+    })),
+  };
+});
+
+jest.mock("fs-extra", () => ({
+  readdir: jest.fn().mockResolvedValue(["init-0000.sql"]),
+  readFile: jest
+    .fn()
+    .mockResolvedValue(Buffer.from("CREATE TABLE metadata ();")),
+}));
+
+jest.mock("@devopsplaybook.io/otel-utils", () => ({
+  StandardTracer: jest.fn(),
+  StandardLogger: jest.fn(),
+  ModuleLogger: jest.fn(),
+}));
+
+jest.mock("@opentelemetry/sdk-trace-base", () => ({
+  Span: jest.fn(),
+}));
+
+jest.mock("@opentelemetry/api", () => ({
+  SpanStatusCode: { ERROR: 2, OK: 1 },
+}));
+
+describe("PostgresDbUtils", () => {
+  let PostgresDbUtils: typeof import("./PostgresDbUtils");
+
+  const mockSpan = {
+    end: jest.fn(),
+    addEvent: jest.fn(),
+    setStatus: jest.fn(),
+  };
+
+  const mockModuleLogger = {
+    info: jest.fn(),
+    error: jest.fn(),
+    warn: jest.fn(),
+  };
+
+  const mockTracer = {
+    startSpan: jest.fn().mockReturnValue(mockSpan),
+  };
+
+  const mockLogger = {
+    createModuleLogger: jest.fn().mockReturnValue(mockModuleLogger),
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.isolateModules(() => {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      PostgresDbUtils = require("./PostgresDbUtils");
+    });
+    PostgresDbUtils.PostgresDbUtilsSetOTel(
+      mockTracer as any,
+      mockLogger as any,
+    );
+  });
+
+  it("PostgresDbUtilsSetOTel should accept tracer and logger", () => {
+    expect(() =>
+      PostgresDbUtils.PostgresDbUtilsSetOTel(
+        mockTracer as any,
+        mockLogger as any,
+      ),
+    ).not.toThrow();
+  });
+
+  it("PostgresDbUtilsGetPool should return undefined before init", () => {
+    expect(PostgresDbUtils.PostgresDbUtilsGetPool()).toBeUndefined();
+  });
+
+  it("PostgresDbUtilsExecSQL should create a span and call pool.query", async () => {
+    const config = {
+      DATABASE_POSTGRES_HOST: "localhost",
+      DATABASE_POSTGRES_PORT: 5432,
+      DATABASE_POSTGRES_USER: "user",
+      DATABASE_POSTGRES_PASSWORD: "pass",
+      DATABASE_POSTGRES_DATABASE: "testdb",
+    };
+
+    // Mock the version query to return version 0
+    // pool.query can be called with 2 args (sql, cb) or 3 args (sql, params, cb)
+    mockQuery.mockImplementation((...args: any[]) => {
+      const cb =
+        typeof args[args.length - 1] === "function"
+          ? args[args.length - 1]
+          : null;
+      if (!cb) return;
+      // Determine which call this is based on arg count
+      if (args.length === 2) {
+        // execSQLFile call
+        cb(null);
+      } else if (args.length === 3) {
+        const sql = args[0] as string;
+        if (sql.includes("MAX")) {
+          // version query
+          cb(null, { rows: [{ version: 0 }] });
+        } else {
+          // insert version
+          cb(null, { rowCount: 1 });
+        }
+      }
+    });
+
+    await PostgresDbUtils.PostgresDbUtilsInit(
+      mockSpan as any,
+      config,
+      "/fake/sql",
+    );
+
+    expect(mockTracer.startSpan).toHaveBeenCalledWith(
+      "PostgresDbUtilsInit",
+      mockSpan,
+    );
+  });
+
+  it("PostgresDbUtilsTransactionStart should call BEGIN", async () => {
+    const config = {
+      DATABASE_POSTGRES_HOST: "localhost",
+      DATABASE_POSTGRES_PORT: 5432,
+      DATABASE_POSTGRES_USER: "user",
+      DATABASE_POSTGRES_PASSWORD: "pass",
+      DATABASE_POSTGRES_DATABASE: "testdb",
+    };
+
+    // Need to init first to create pool
+    mockQuery.mockImplementation((_sql: any, ...args: any[]) => {
+      const cb = args[args.length - 1];
+      if (typeof cb === "function") cb(null, { rows: [], rowCount: 0 });
+    });
+
+    await PostgresDbUtils.PostgresDbUtilsInit(
+      mockSpan as any,
+      config,
+      "/fake/sql",
+    );
+    await PostgresDbUtils.PostgresDbUtilsTransactionStart(mockSpan as any);
+
+    expect(mockTracer.startSpan).toHaveBeenCalledWith(
+      "PostgresDbUtilsTransactionStart",
+      mockSpan,
+    );
+  });
+});

package/src/PostgresDbUtils.ts

@@ -0,0 +1,233 @@
+import { Pool } from "pg";
+import * as fs from "fs-extra";
+import { Span } from "@opentelemetry/sdk-trace-base";
+import { SpanStatusCode } from "@opentelemetry/api";
+import {
+  StandardTracer,
+  StandardLogger,
+  ModuleLogger,
+} 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;
+}
+
+let pool: Pool;
+let tracer: StandardTracer;
+let logger: ModuleLogger;
+
+/**
+ * Injects the OTel tracer and logger instances used by all Postgres operations.
+ * Must be called once at startup, before {@link PostgresDbUtilsInit}.
+ */
+export function PostgresDbUtilsSetOTel(
+  tracerIn: StandardTracer,
+  loggerIn: StandardLogger,
+): void {
+  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.
+ */
+export async function PostgresDbUtilsInit(
+  context: Span,
+  config: PostgresDbConfig,
+  sqlDir: string,
+): Promise<void> {
+  const span = tracer.startSpan("PostgresDbUtilsInit", context);
+
+  pool = new 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: Error) => {
+    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. */
+export function PostgresDbUtilsGetPool(): Pool {
+  return pool;
+}
+
+/**
+ * Execute a write SQL statement with OTel tracing.
+ * @returns Number of rows changed.
+ */
+export function PostgresDbUtilsExecSQL(
+  context: Span,
+  sql: string,
+  params: unknown[] = [],
+): Promise<number> {
+  const span = tracer.startSpan("PostgresDbUtilsExecSQL", context);
+  return new Promise((resolve, reject) => {
+    pool.query(
+      sql,
+      params,
+      (error: Error | null, result: { rowCount: number | null }) => {
+        if (error) {
+          span.setStatus({
+            code: 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). */
+export async function PostgresDbUtilsExecSQLFile(
+  context: Span,
+  filename: string,
+): Promise<void> {
+  const span = tracer.startSpan("PostgresDbUtilsExecSQLFile", context);
+  const sql = (await fs.readFile(filename)).toString();
+  return new Promise((resolve, reject) => {
+    pool.query(sql, (error: Error | null) => {
+      if (error) {
+        span.setStatus({ code: 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.
+ */
+export function PostgresDbUtilsQuerySQL(
+  context: Span,
+  sql: string,
+  params: unknown[] = [],
+  debug = false,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): Promise<any[]> {
+  const span = tracer.startSpan("PostgresDbUtilsQuerySQL", context);
+  if (debug) {
+    console.log(sql);
+  }
+  return new Promise((resolve, reject) => {
+    pool.query(
+      sql,
+      params,
+      (error: Error | null, result: { rows: unknown[] }) => {
+        if (error) {
+          span.setStatus({
+            code: 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. */
+export function PostgresDbUtilsTransactionStart(context: Span): Promise<void> {
+  const span = tracer.startSpan("PostgresDbUtilsTransactionStart", context);
+  return new Promise((resolve, reject) => {
+    pool.query("BEGIN", (error: Error | null) => {
+      if (error) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+        span.end();
+        reject(error);
+      } else {
+        span.end();
+        resolve();
+      }
+    });
+  });
+}
+
+/** Commit a transaction. */
+export function PostgresDbUtilsTransactionCommit(context: Span): Promise<void> {
+  const span = tracer.startSpan("PostgresDbUtilsTransactionCommit", context);
+  return new Promise((resolve, reject) => {
+    pool.query("COMMIT", (error: Error | null) => {
+      if (error) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+        span.end();
+        reject(error);
+      } else {
+        span.end();
+        resolve();
+      }
+    });
+  });
+}