@forwardimpact/libutil 0.1.60

package/test/logger.test.js

@@ -0,0 +1,322 @@
+import { test, describe, beforeEach, afterEach } from "node:test";
+import assert from "node:assert";
+
+// Module under test
+import { Logger, createLogger } from "@forwardimpact/libtelemetry";
+
+describe("Logger", () => {
+  let originalDebug;
+  let consoleOutput;
+  let originalConsoleError;
+
+  beforeEach(() => {
+    originalDebug = process.env.DEBUG;
+    consoleOutput = [];
+    originalConsoleError = console.error;
+    console.error = (message) => consoleOutput.push(message);
+  });
+
+  afterEach(() => {
+    process.env.DEBUG = originalDebug;
+    console.error = originalConsoleError;
+  });
+
+  test("creates Logger with domain", () => {
+    const logger = new Logger("test");
+
+    assert.ok(logger instanceof Logger);
+    assert.strictEqual(logger.domain, "test");
+  });
+
+  test("validates constructor parameters", () => {
+    assert.throws(() => new Logger(), {
+      message: /domain must be a non-empty string/,
+    });
+    assert.throws(() => new Logger(""), {
+      message: /domain must be a non-empty string/,
+    });
+    assert.throws(() => new Logger(null), {
+      message: /domain must be a non-empty string/,
+    });
+  });
+
+  test("enables logging when DEBUG=*", () => {
+    process.env.DEBUG = "*";
+    const logger = new Logger("test");
+
+    assert.strictEqual(logger.enabled, true);
+  });
+
+  test("disables logging when DEBUG is empty", () => {
+    process.env.DEBUG = "";
+    const logger = new Logger("test");
+
+    assert.strictEqual(logger.enabled, false);
+  });
+
+  test("enables logging for exact domain match", () => {
+    process.env.DEBUG = "test,other";
+    const logger = new Logger("test");
+
+    assert.strictEqual(logger.enabled, true);
+  });
+
+  test("enables logging for wildcard pattern match", () => {
+    process.env.DEBUG = "test*";
+    const logger = new Logger("test:service");
+
+    assert.strictEqual(logger.enabled, true);
+  });
+
+  test("disables logging for non-matching domain", () => {
+    process.env.DEBUG = "other";
+    const logger = new Logger("test");
+
+    assert.strictEqual(logger.enabled, false);
+  });
+
+  test("logs debug message when enabled", () => {
+    process.env.DEBUG = "test";
+    const logger = new Logger("test");
+
+    logger.debug("TestApp", "Test message");
+
+    assert.strictEqual(consoleOutput.length, 1);
+    assert.ok(consoleOutput[0].includes("DEBUG"));
+    assert.ok(consoleOutput[0].includes("test"));
+    assert.ok(consoleOutput[0].includes("TestApp"));
+    assert.ok(consoleOutput[0].includes("Test message"));
+  });
+
+  test("does not log when disabled", () => {
+    process.env.DEBUG = "other";
+    const logger = new Logger("test");
+
+    logger.debug("TestApp", "Test message");
+
+    assert.strictEqual(consoleOutput.length, 0);
+  });
+
+  test(
+    "logs message with data object",
+    { skip: "Future PR will fix this" },
+    () => {
+      process.env.DEBUG = "test";
+      const logger = new Logger("test");
+
+      logger.debug("ProcessMethod", "Processing", {
+        items: "50/200",
+        retry: "2/3",
+      });
+
+      assert.strictEqual(consoleOutput.length, 1);
+      assert.ok(consoleOutput[0].includes("DEBUG"));
+      assert.ok(consoleOutput[0].includes("test"));
+      assert.ok(consoleOutput[0].includes("ProcessMethod"));
+      assert.ok(consoleOutput[0].includes("Processing"));
+      assert.ok(consoleOutput[0].includes('items="50/200"'));
+      assert.ok(consoleOutput[0].includes('retry="2/3"'));
+    },
+  );
+
+  test("handles empty data object", () => {
+    process.env.DEBUG = "test";
+    const logger = new Logger("test");
+
+    logger.debug("TestApp", "Test message", {});
+
+    assert.strictEqual(consoleOutput.length, 1);
+    assert.ok(consoleOutput[0].includes("DEBUG"));
+    assert.ok(consoleOutput[0].includes("Test message"));
+  });
+
+  test("includes timestamp in log output", () => {
+    process.env.DEBUG = "test";
+    const logger = new Logger("test");
+
+    logger.debug("TestApp", "Test message");
+
+    assert.strictEqual(consoleOutput.length, 1);
+    assert.ok(consoleOutput[0].match(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/));
+  });
+
+  test(
+    "extracts trace context from error objects",
+    { skip: "Future PR will fix this" },
+    () => {
+      process.env.DEBUG = "test";
+      const logger = new Logger("test");
+
+      // Create error with trace context (as added by Tracer)
+      const error = new Error("Test error");
+      Object.defineProperties(error, {
+        trace_id: {
+          value: "abc123def456",
+          enumerable: false,
+          writable: false,
+        },
+        span_id: {
+          value: "789xyz012",
+          enumerable: false,
+          writable: false,
+        },
+        service_name: {
+          value: "test-service",
+          enumerable: false,
+          writable: false,
+        },
+      });
+
+      logger.error("TestMethod", error);
+
+      assert.strictEqual(consoleOutput.length, 1);
+      assert.ok(consoleOutput[0].includes("ERROR"));
+      assert.ok(consoleOutput[0].includes("Test error"));
+      assert.ok(
+        consoleOutput[0].includes("trace_id=abc123def456"),
+        "Should include trace_id in structured data",
+      );
+      assert.ok(
+        consoleOutput[0].includes("span_id=789xyz012"),
+        "Should include span_id in structured data",
+      );
+      assert.ok(
+        consoleOutput[0].includes("service_name=test-service"),
+        "Should include service_name in structured data",
+      );
+    },
+  );
+
+  test(
+    "merges trace context with provided attributes",
+    { skip: "Future PR will fix this" },
+    () => {
+      process.env.DEBUG = "test";
+      const logger = new Logger("test");
+
+      const error = new Error("Test error");
+      Object.defineProperty(error, "trace_id", {
+        value: "trace123",
+        enumerable: false,
+        writable: false,
+      });
+
+      logger.error("TestMethod", error, { retry: "1/3", status: "500" });
+
+      assert.strictEqual(consoleOutput.length, 1);
+      assert.ok(consoleOutput[0].includes("ERROR"));
+      assert.ok(consoleOutput[0].includes("Test error"));
+      assert.ok(
+        consoleOutput[0].includes('trace_id="abc123def456"'),
+        "Should include trace_id in structured data",
+      );
+      assert.ok(
+        consoleOutput[0].includes('span_id="789xyz012"'),
+        "Should include span_id in structured data",
+      );
+      assert.ok(
+        consoleOutput[0].includes('service_name="test-service"'),
+        "Should include service_name in structured data",
+      );
+    },
+  );
+
+  test("merges trace context with provided attributes", () => {
+    process.env.DEBUG = "test";
+    const logger = new Logger("test");
+
+    const error = new Error("Test error");
+    Object.defineProperty(error, "trace_id", {
+      value: "trace123",
+      enumerable: false,
+      writable: false,
+    });
+
+    logger.error("TestMethod", error, { retry: "1/3", status: "500" });
+
+    assert.strictEqual(consoleOutput.length, 1);
+    assert.ok(consoleOutput[0].includes('trace_id="trace123"'));
+    assert.ok(consoleOutput[0].includes('retry="1/3"'));
+    assert.ok(consoleOutput[0].includes('status="500"'));
+  });
+
+  test("exception logs message when disabled", () => {
+    process.env.DEBUG = "other";
+    const logger = new Logger("test");
+
+    const error = new Error("Test error");
+
+    logger.exception("TestMethod", error);
+
+    assert.strictEqual(consoleOutput.length, 1);
+    assert.ok(consoleOutput[0].includes("ERROR"));
+    assert.ok(consoleOutput[0].includes("Test error"));
+    assert.ok(
+      !consoleOutput[0].includes("at "),
+      "Should not include stack trace when disabled",
+    );
+  });
+
+  test("exception logs message with stack trace when enabled", () => {
+    process.env.DEBUG = "test";
+    const logger = new Logger("test");
+
+    const error = new Error("Test error");
+
+    logger.exception("TestMethod", error);
+
+    assert.strictEqual(consoleOutput.length, 1);
+    assert.ok(consoleOutput[0].includes("ERROR"));
+    assert.ok(consoleOutput[0].includes("Test error"));
+    assert.ok(
+      consoleOutput[0].includes("at "),
+      "Should include stack trace when enabled",
+    );
+  });
+
+  test("exception extracts trace context from error", () => {
+    process.env.DEBUG = "test";
+    const logger = new Logger("test");
+
+    const error = new Error("Test error");
+    error.trace_id = "trace456";
+    error.span_id = "span789";
+    error.service_name = "my-service";
+
+    logger.exception("TestMethod", error);
+
+    assert.strictEqual(consoleOutput.length, 1);
+    assert.ok(consoleOutput[0].includes('trace_id="trace456"'));
+    assert.ok(consoleOutput[0].includes('span_id="span789"'));
+    assert.ok(consoleOutput[0].includes('service_name="my-service"'));
+  });
+
+  test("exception merges trace context with provided attributes", () => {
+    process.env.DEBUG = "test";
+    const logger = new Logger("test");
+
+    const error = new Error("Test error");
+    error.trace_id = "trace123";
+
+    logger.exception("TestMethod", error, { retry: "2/3" });
+
+    assert.strictEqual(consoleOutput.length, 1);
+    assert.ok(consoleOutput[0].includes('trace_id="trace123"'));
+    assert.ok(consoleOutput[0].includes('retry="2/3"'));
+  });
+});
+
+describe("createLogger", () => {
+  test("creates Logger instance", () => {
+    const logger = createLogger("test");
+
+    assert.ok(logger instanceof Logger);
+    assert.strictEqual(logger.domain, "test");
+  });
+
+  test("passes through domain validation", () => {
+    assert.throws(() => createLogger(""), {
+      message: /domain must be a non-empty string/,
+    });
+  });
+});

package/test/processor.test.js

@@ -0,0 +1,140 @@
+import { test, describe, beforeEach } from "node:test";
+import assert from "node:assert";
+
+import { createSilentLogger } from "@forwardimpact/libharness";
+
+// Module under test
+import { ProcessorBase } from "../processor.js";
+
+describe("ProcessorBase", () => {
+  let mockLogger;
+
+  beforeEach(() => {
+    mockLogger = createSilentLogger();
+  });
+
+  describe("constructor", () => {
+    test("creates ProcessorBase with logger and batch size", () => {
+      const processor = new ProcessorBase(mockLogger, 5);
+
+      assert.ok(processor instanceof ProcessorBase);
+    });
+
+    test("validates logger parameter", () => {
+      assert.throws(() => new ProcessorBase(), {
+        message: /logger is required/,
+      });
+      assert.throws(() => new ProcessorBase(null), {
+        message: /logger is required/,
+      });
+    });
+
+    test("validates batch size parameter", () => {
+      assert.throws(() => new ProcessorBase(mockLogger, 0), {
+        message: /batchSize must be a positive number/,
+      });
+      assert.throws(() => new ProcessorBase(mockLogger, -1), {
+        message: /batchSize must be a positive number/,
+      });
+      assert.throws(() => new ProcessorBase(mockLogger, "invalid"), {
+        message: /batchSize must be a positive number/,
+      });
+    });
+
+    test("uses default batch size when not provided", () => {
+      const processor = new ProcessorBase(mockLogger);
+      // Test passes if no error is thrown
+      assert.ok(processor instanceof ProcessorBase);
+    });
+  });
+
+  describe("process", () => {
+    test("validates items parameter", async () => {
+      const processor = new ProcessorBase(mockLogger, 2);
+
+      await assert.rejects(() => processor.process("not-array"), {
+        message: /items must be an array/,
+      });
+    });
+
+    test("handles empty array", async () => {
+      const processor = new ProcessorBase(mockLogger, 2);
+
+      // Should not throw
+      await processor.process([]);
+    });
+
+    test("calls processItem for each item", async () => {
+      /** Test processor that tracks processed items */
+      class TestProcessor extends ProcessorBase {
+        /**
+         * Creates a test processor
+         * @param {object} logger - Logger instance
+         */
+        constructor(logger) {
+          super(logger, 2);
+          this.processedItems = [];
+        }
+
+        /**
+         * Processes a single item
+         * @param {any} item - Item to process
+         * @returns {Promise<string>} Processed result
+         */
+        async processItem(item) {
+          this.processedItems.push(item);
+          return `processed-${item}`;
+        }
+      }
+
+      const processor = new TestProcessor(mockLogger);
+      await processor.process(["a", "b", "c", "d"]);
+
+      assert.strictEqual(processor.processedItems.length, 4);
+      assert.deepStrictEqual(processor.processedItems, ["a", "b", "c", "d"]);
+    });
+
+    test("continues processing when individual items fail", async () => {
+      /** Test processor that simulates failures */
+      class TestProcessor extends ProcessorBase {
+        /**
+         * Creates a test processor
+         * @param {object} logger - Logger instance
+         */
+        constructor(logger) {
+          super(logger, 3);
+          this.processedItems = [];
+        }
+
+        /**
+         * Processes a single item with failure simulation
+         * @param {any} item - Item to process
+         * @returns {Promise<string>} Processed result
+         */
+        async processItem(item) {
+          if (item === "fail") {
+            throw new Error("Simulated failure");
+          }
+          this.processedItems.push(item);
+          return `processed-${item}`;
+        }
+      }
+
+      const processor = new TestProcessor(mockLogger);
+      await processor.process(["a", "fail", "b", "c"]);
+
+      // Should have processed all items except the failing one
+      assert.deepStrictEqual(processor.processedItems, ["a", "b", "c"]);
+    });
+  });
+
+  describe("processItem", () => {
+    test("throws error when not implemented", async () => {
+      const processor = new ProcessorBase(mockLogger, 2);
+
+      await assert.rejects(() => processor.processItem("item"), {
+        message: /processItem must be implemented by subclass/,
+      });
+    });
+  });
+});

package/test/retry.test.js

@@ -0,0 +1,194 @@
+import { test, describe, beforeEach, mock } from "node:test";
+import assert from "node:assert";
+
+// Module under test
+import { Retry } from "../retry.js";
+
+describe("Retry", () => {
+  let retry;
+
+  beforeEach(() => {
+    // Use very short delay for testing to speed up retry tests
+    retry = new Retry({ delay: 1 });
+  });
+
+  test("creates retry instance with default config", () => {
+    const defaultRetry = new Retry();
+    assert.ok(defaultRetry instanceof Retry);
+  });
+
+  test("creates retry instance with custom config", () => {
+    const customRetry = new Retry({ retries: 5, delay: 500 });
+    assert.ok(customRetry instanceof Retry);
+  });
+
+  test("retry mechanism works with exhausted retries on 429", async () => {
+    const retryResponse = {
+      ok: false,
+      status: 429,
+      statusText: "Too Many Requests",
+    };
+
+    const mockFetch = mock.fn(() => Promise.resolve(retryResponse));
+
+    const response = await retry.execute(mockFetch);
+
+    // Should exhaust all retries and return the 429 response
+    assert.strictEqual(mockFetch.mock.callCount(), 11); // Initial + 10 retries
+    assert.strictEqual(response.status, 429);
+  });
+
+  test("retries on 502 Bad Gateway errors", async () => {
+    const retryResponse = {
+      ok: false,
+      status: 502,
+      statusText: "Bad Gateway",
+    };
+    const successResponse = {
+      ok: true,
+      status: 200,
+      json: mock.fn(() => Promise.resolve({ data: "success" })),
+    };
+
+    let callCount = 0;
+    const mockFetch = mock.fn(() => {
+      callCount++;
+      if (callCount === 1) {
+        return Promise.resolve(retryResponse);
+      }
+      return Promise.resolve(successResponse);
+    });
+
+    const result = await retry.execute(mockFetch);
+
+    // Should retry once and succeed
+    assert(mockFetch.mock.callCount() >= 2);
+    assert.strictEqual(result.ok, true);
+  });
+
+  test("retries on 503 Service Unavailable errors", async () => {
+    const retryResponse = {
+      ok: false,
+      status: 503,
+      statusText: "Service Unavailable",
+    };
+    const successResponse = {
+      ok: true,
+      status: 200,
+      json: mock.fn(() => Promise.resolve({ data: "success" })),
+    };
+
+    let callCount = 0;
+    const mockFetch = mock.fn(() => {
+      callCount++;
+      if (callCount === 1) {
+        return Promise.resolve(retryResponse);
+      }
+      return Promise.resolve(successResponse);
+    });
+
+    const result = await retry.execute(mockFetch);
+
+    // Should retry once and succeed
+    assert(mockFetch.mock.callCount() >= 2);
+    assert.strictEqual(result.ok, true);
+  });
+
+  test("retries on 504 Gateway Timeout errors", async () => {
+    const retryResponse = {
+      ok: false,
+      status: 504,
+      statusText: "Gateway Timeout",
+    };
+    const successResponse = {
+      ok: true,
+      status: 200,
+      json: mock.fn(() => Promise.resolve({ data: "success" })),
+    };
+
+    let callCount = 0;
+    const mockFetch = mock.fn(() => {
+      callCount++;
+      if (callCount <= 2) {
+        return Promise.resolve(retryResponse);
+      }
+      return Promise.resolve(successResponse);
+    });
+
+    const result = await retry.execute(mockFetch);
+
+    // Should retry twice and succeed
+    assert(mockFetch.mock.callCount() >= 3);
+    assert.strictEqual(result.ok, true);
+  });
+
+  test("retries on network errors", async () => {
+    const successResponse = {
+      ok: true,
+      status: 200,
+      json: mock.fn(() => Promise.resolve({ data: "success" })),
+    };
+
+    let callCount = 0;
+    const mockFetch = mock.fn(() => {
+      callCount++;
+      if (callCount === 1) {
+        return Promise.reject(new Error("Network error: Connection refused"));
+      }
+      return Promise.resolve(successResponse);
+    });
+
+    const result = await retry.execute(mockFetch);
+
+    // Should retry once and succeed
+    assert(mockFetch.mock.callCount() >= 2);
+    assert.strictEqual(result.ok, true);
+  });
+
+  test("non-retryable errors do not trigger retries", async () => {
+    const errorResponse = {
+      ok: false,
+      status: 400,
+      statusText: "Bad Request",
+    };
+
+    const mockFetch = mock.fn(() => Promise.resolve(errorResponse));
+
+    const response = await retry.execute(mockFetch);
+
+    // Should only make one call for non-retryable errors
+    assert.strictEqual(mockFetch.mock.callCount(), 1);
+    assert.strictEqual(response.status, 400);
+  });
+
+  test("500 Internal Server Error triggers retries", async () => {
+    const errorResponse = {
+      ok: false,
+      status: 500,
+      statusText: "Internal Server Error",
+    };
+
+    const mockFetch = mock.fn(() => Promise.resolve(errorResponse));
+
+    const response = await retry.execute(mockFetch);
+
+    // Should retry for 500 errors (retries + 1 initial attempt = 11 calls)
+    assert.strictEqual(mockFetch.mock.callCount(), 11);
+    assert.strictEqual(response.status, 500);
+  });
+
+  test("executes successfully without validation function", async () => {
+    const successResponse = {
+      ok: true,
+      status: 200,
+      json: mock.fn(() => Promise.resolve({ data: "success" })),
+    };
+
+    const mockFetch = mock.fn(() => Promise.resolve(successResponse));
+
+    const result = await retry.execute(mockFetch);
+
+    assert.strictEqual(mockFetch.mock.callCount(), 1);
+    assert.strictEqual(result.ok, true);
+  });
+});