feat(sdk): add configureLogger method with modeAware option

Replace setCustomLogger() with configureLogger() that accepts LoggerConfig
object with customLogger and modeAware options. The modeAware flag controls
whether logs are suppressed during replay mode (default: false).

Changes:
- Add configureLogger(config: LoggerConfig) method to DurableContext
- Add LoggerConfig interface with customLogger and modeAware properties
- Update createModeAwareLogger to accept modeAwareEnabled parameter
- Change default modeAware behavior to false (show logs during replay)
- Update all tests to reflect new default behavior
- Add logger-test example with file-based logging (local-only tests)
- Update documentation: README, API_SPECIFICATION.md with new API
- Add TSDoc comments for Logger types and configureLogger method

Author: ParidelPooya

packages/aws-durable-execution-sdk-js-examples/src/examples/logger-example/logger-example.test.ts

@@ -0,0 +1,82 @@
+import { handler } from "./logger-after-callback";
+import { createTests } from "../../../utils/test-helper";
+import {
+  InvocationType,
+  WaitingOperationStatus,
+} from "@aws/durable-execution-sdk-js-testing";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+createTests({
+  name: "logger-after-callback",
+  functionName: "logger-after-callback",
+  handler,
+  invocationType: InvocationType.Event,
+  tests: (runner, isCloud) => {
+    if (!isCloud) {
+      it("should log after createCallback in execution mode with modeAware=true", async () => {
+        const logFilePath = path.join(
+          os.tmpdir(),
+          `logger-test-${Date.now()}.log`,
+        );
+
+        if (fs.existsSync(logFilePath)) {
+          fs.unlinkSync(logFilePath);
+        }
+
+        try {
+          const executionPromise = runner.run({
+            payload: { logFilePath, modeAware: true },
+          });
+
+          const callbackOp = runner.getOperationByIndex(0);
+          await callbackOp.waitForData(WaitingOperationStatus.STARTED);
+          await callbackOp.sendCallbackSuccess("test-result");
+
+          const execution = await executionPromise;
+
+          const result = execution.getResult() as any;
+          expect(result.message).toBe("Success");
+          expect(result.callbackId).toBeDefined();
+          expect(result.result).toBe("test-result");
+
+          const logContent = fs.readFileSync(logFilePath, "utf-8");
+          const logLines = logContent
+            .trim()
+            .split("\n")
+            .map((line) => JSON.parse(line));
+
+          const beforeCallbackLogs = logLines.filter(
+            (log) => log.message === "Before createCallback",
+          );
+          const afterCallbackLogs = logLines.filter(
+            (log) => log.message === "After createCallback",
+          );
+
+          // With modeAware: true:
+          // - "Before createCallback" appears once (execution mode, before createCallback)
+          // - "After createCallback" appears twice (once after createCallback returns, once after callback resolves)
+          expect(beforeCallbackLogs.length).toBe(1);
+          expect(afterCallbackLogs.length).toBe(2);
+        } finally {
+          if (fs.existsSync(logFilePath)) {
+            fs.unlinkSync(logFilePath);
+          }
+        }
+      });
+    }
+
+    it("should execute successfully", async () => {
+      const executionPromise = runner.run();
+
+      const callbackOp = runner.getOperationByIndex(0);
+      await callbackOp.waitForData(WaitingOperationStatus.STARTED);
+      await callbackOp.sendCallbackSuccess("test-result");
+
+      const execution = await executionPromise;
+      const result = execution.getResult() as any;
+      expect(result.message).toBe("Success");
+    });
+  },
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/logger-example/logger-example.ts

@@ -0,0 +1,70 @@
+import { withDurableExecution, Logger } from "@aws/durable-execution-sdk-js";
+import { ExampleConfig } from "../../../types";
+import * as fs from "fs";
+
+export const config: ExampleConfig = {
+  name: "Logger After Callback",
+  description: "Test logger mode switching after createCallback operation",
+};
+
+interface LoggerTestEvent {
+  logFilePath?: string;
+  modeAware?: boolean;
+}
+
+export const handler = withDurableExecution(
+  async (event: LoggerTestEvent, context) => {
+    if (event.logFilePath) {
+      const fileLogger: Logger = {
+        log: (level, message, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level, message, data }) + "\n",
+          );
+        },
+        info: (message, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level: "info", message, data }) + "\n",
+          );
+        },
+        error: (message, error, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level: "error", message, error, data }) + "\n",
+          );
+        },
+        warn: (message, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level: "warn", message, data }) + "\n",
+          );
+        },
+        debug: (message, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level: "debug", message, data }) + "\n",
+          );
+        },
+      };
+
+      context.configureLogger({
+        customLogger: fileLogger,
+        modeAware: event.modeAware ?? true,
+      });
+    } else {
+      context.configureLogger({ modeAware: event.modeAware ?? true });
+    }
+
+    context.logger.info("Before createCallback");
+
+    const [callbackPromise, callbackId] =
+      await context.createCallback<string>();
+
+    context.logger.info("After createCallback");
+
+    const result = await callbackPromise;
+
+    return { message: "Success", callbackId, result };
+  },
+);

packages/aws-durable-execution-sdk-js-examples/src/examples/logger-test/after-callback/logger-after-callback.test.ts

@@ -0,0 +1,59 @@
+import { handler } from "./logger-after-wait";
+import { createTests } from "../../../utils/test-helper";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+createTests({
+  name: "logger-after-wait",
+  functionName: "logger-after-wait",
+  handler,
+  tests: (runner, isCloud) => {
+    if (!isCloud) {
+      it("should log after wait in execution mode with modeAware=true", async () => {
+        const logFilePath = path.join(
+          os.tmpdir(),
+          `logger-test-${Date.now()}.log`,
+        );
+
+        if (fs.existsSync(logFilePath)) {
+          fs.unlinkSync(logFilePath);
+        }
+
+        try {
+          const execution = await runner.run({
+            payload: { logFilePath, modeAware: true },
+          });
+
+          expect(execution.getResult()).toEqual({ message: "Success" });
+
+          const logContent = fs.readFileSync(logFilePath, "utf-8");
+          const logLines = logContent
+            .trim()
+            .split("\n")
+            .map((line) => JSON.parse(line));
+
+          const beforeWaitLogs = logLines.filter(
+            (log) => log.message === "Before wait",
+          );
+          const afterWaitLogs = logLines.filter(
+            (log) => log.message === "After wait",
+          );
+
+          // With modeAware: true, both logs appear once (execution mode only)
+          expect(beforeWaitLogs.length).toBe(1);
+          expect(afterWaitLogs.length).toBe(1);
+        } finally {
+          if (fs.existsSync(logFilePath)) {
+            fs.unlinkSync(logFilePath);
+          }
+        }
+      });
+    }
+
+    it("should execute successfully", async () => {
+      const execution = await runner.run();
+      expect(execution.getResult()).toEqual({ message: "Success" });
+    });
+  },
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/logger-test/after-callback/logger-after-callback.ts

@@ -0,0 +1,65 @@
+import { withDurableExecution, Logger } from "@aws/durable-execution-sdk-js";
+import { ExampleConfig } from "../../../types";
+import * as fs from "fs";
+
+export const config: ExampleConfig = {
+  name: "Logger After Wait",
+  description: "Test logger mode switching after wait operation",
+};
+
+interface LoggerTestEvent {
+  logFilePath?: string;
+  modeAware?: boolean;
+}
+
+export const handler = withDurableExecution(
+  async (event: LoggerTestEvent, context) => {
+    if (event.logFilePath) {
+      const fileLogger: Logger = {
+        log: (level, message, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level, message, data }) + "\n",
+          );
+        },
+        info: (message, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level: "info", message, data }) + "\n",
+          );
+        },
+        error: (message, error, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level: "error", message, error, data }) + "\n",
+          );
+        },
+        warn: (message, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level: "warn", message, data }) + "\n",
+          );
+        },
+        debug: (message, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level: "debug", message, data }) + "\n",
+          );
+        },
+      };
+
+      context.configureLogger({
+        customLogger: fileLogger,
+        modeAware: event.modeAware ?? true,
+      });
+    } else {
+      context.configureLogger({ modeAware: event.modeAware ?? true });
+    }
+
+    context.logger.info("Before wait");
+    await context.wait({ seconds: 2 });
+    context.logger.info("After wait");
+
+    return { message: "Success" };
+  },
+);