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

package/src/DbUtilsNoTelemetry.spec.ts

@@ -0,0 +1,174 @@
+import {
+  DbUtilsNoTelemetryBatchInsert,
+  DbUtilsNoTelemetryExecSQL,
+  DbUtilsNoTelemetryQuerySQL,
+} from "./DbUtilsNoTelemetry";
+
+/* eslint-disable @typescript-eslint/no-unsafe-function-type */
+
+// Shared mock DB handle – defined BEFORE jest.mock factory so it's hoisted correctly.
+// We use jest.fn() at module scope; the mock factory captures the same reference.
+const mockPrepare = jest.fn(() => ({
+  run: jest.fn().mockReturnValue({ changes: 0 }),
+  all: jest.fn().mockReturnValue([]),
+}));
+const mockQuery = jest.fn();
+const mockDbHandle = { prepare: mockPrepare, query: mockQuery };
+
+let currentDbType: "sqlite" | "postgres" = "sqlite";
+
+jest.mock("./DbUtils", () => ({
+  DbUtilsGetDatabase: jest.fn(() => mockDbHandle),
+  DbUtilsGetType: jest.fn(() => currentDbType),
+  convertToPostgresPlaceholders: jest.fn((sql: string) => {
+    let idx = 1;
+    return sql.replace(/\?/g, () => `$${idx++}`);
+  }),
+}));
+
+jest.mock("@devopsplaybook.io/otel-utils", () => ({
+  ModuleLogger: jest.fn(),
+  StandardLogger: jest.fn(),
+}));
+
+import * as DbUtilsNoTelemetryModule from "./DbUtilsNoTelemetry";
+
+beforeAll(() => {
+  const mockLogger = {
+    error: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  } as any;
+  DbUtilsNoTelemetryModule.DbUtilsNoTelemetrySetLogger({
+    createModuleLogger: () => mockLogger,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  } as any);
+});
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  currentDbType = "sqlite";
+});
+
+describe("DbUtilsNoTelemetryBatchInsert", () => {
+  it("returns 0 for empty rows", () => {
+    const result = DbUtilsNoTelemetryBatchInsert("INTO t (c)", 1, []);
+    expect(result).toBe(0);
+  });
+
+  it("generates correct multi-row VALUES SQL (sqlite)", () => {
+    currentDbType = "sqlite";
+    mockPrepare.mockReturnValue({
+      run: jest.fn().mockReturnValue({ changes: 2 }),
+      all: jest.fn(),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any);
+
+    const rows = [
+      ["a1", "b1"],
+      ["a2", "b2"],
+    ];
+    const result = DbUtilsNoTelemetryBatchInsert("INTO t (c1,c2)", 2, rows);
+    expect(result).toBe(2);
+  });
+});
+
+describe("DbUtilsNoTelemetryExecSQL (sqlite)", () => {
+  beforeEach(() => {
+    currentDbType = "sqlite";
+  });
+
+  it("resolves with changes count on success", () => {
+    mockPrepare.mockReturnValue({
+      run: jest.fn().mockReturnValue({ changes: 3 }),
+      all: jest.fn(),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any);
+
+    const result = DbUtilsNoTelemetryExecSQL("INSERT INTO t (c) VALUES (?)", [
+      "x",
+    ]);
+    expect(result).toBe(3);
+  });
+});
+
+describe("DbUtilsNoTelemetryExecSQL (postgres)", () => {
+  beforeEach(() => {
+    currentDbType = "postgres";
+  });
+
+  it("resolves with rowCount on success", async () => {
+    mockQuery.mockImplementation(
+      (_sql: string, _params: unknown[], cb: Function) => {
+        cb(null, { rowCount: 5 });
+      },
+    );
+
+    const result = await DbUtilsNoTelemetryExecSQL(
+      "INSERT INTO t (c) VALUES (?)",
+      ["x"],
+    );
+    expect(result).toBe(5);
+  });
+
+  it("rejects on error", async () => {
+    mockQuery.mockImplementation(
+      (_sql: string, _params: unknown[], cb: Function) => {
+        cb(new Error("deadlock detected"));
+      },
+    );
+
+    await expect(
+      DbUtilsNoTelemetryExecSQL("INSERT INTO t (c) VALUES (?)", ["x"]),
+    ).rejects.toThrow("deadlock detected");
+  });
+});
+
+describe("DbUtilsNoTelemetryQuerySQL (sqlite)", () => {
+  beforeEach(() => {
+    currentDbType = "sqlite";
+  });
+
+  it("returns rows on success", () => {
+    const expectedRows = [{ id: 1 }, { id: 2 }];
+    mockPrepare.mockReturnValue({
+      run: jest.fn(),
+      all: jest.fn().mockReturnValue(expectedRows),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any);
+
+    const result = DbUtilsNoTelemetryQuerySQL("SELECT * FROM t");
+    expect(result).toEqual(expectedRows);
+  });
+});
+
+describe("DbUtilsNoTelemetryQuerySQL (postgres)", () => {
+  beforeEach(() => {
+    currentDbType = "postgres";
+  });
+
+  it("returns rows on success", async () => {
+    const expectedRows = [{ id: 1 }, { id: 2 }];
+    mockQuery.mockImplementation(
+      (_sql: string, _params: unknown[], cb: Function) => {
+        cb(null, { rows: expectedRows });
+      },
+    );
+
+    const result = await DbUtilsNoTelemetryQuerySQL("SELECT * FROM t");
+    expect(result).toEqual(expectedRows);
+  });
+
+  it("rejects on error", async () => {
+    mockQuery.mockImplementation(
+      (_sql: string, _params: unknown[], cb: Function) => {
+        cb(new Error("connection lost"));
+      },
+    );
+
+    await expect(DbUtilsNoTelemetryQuerySQL("SELECT * FROM t")).rejects.toThrow(
+      "connection lost",
+    );
+  });
+});

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