docs/fix: address PR #293 review nits (result guard, whenAny example, @internal, createTimer @remarks)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: YunchuWang

packages/durabletask-js/src/task/context/orchestration-context.ts

@@ -108,6 +108,13 @@ export abstract class OrchestrationContext {
   /**
    * Create a timer task that will fire at a specified time.
    *
+   * @remarks
+   * This abstract method is implemented only by the SDK's own orchestration
+   * context (`RuntimeOrchestrationContext`); orchestrator code consumes a context
+   * instance and does not subclass it. The return type is the concrete
+   * {@link TimerTask} (which is a `Task`) so callers can cancel the timer — this
+   * narrowing is safe for all callers.
+   *
    * @param {Date | number} fireAt The time at which the timer should fire.
    * @returns {TimerTask} A cancellable Durable Timer task that schedules the timer to wake up the orchestrator
    */

packages/durabletask-js/src/task/task.ts

@@ -55,7 +55,7 @@ export class Task<T> {
    * Durable Functions `Task.result` shape.
    */
   get result(): T | undefined {
-    return this._isComplete ? this._result : undefined;
+    return this._isComplete && !this._exception ? this._result : undefined;
   }
 
   /**

packages/durabletask-js/src/task/timer-task.ts

@@ -18,9 +18,11 @@ import { CompletableTask } from "./completable-task";
  *
  * @example Cancel the loser of a race
  * ```typescript
+ * import { whenAny } from "@microsoft/durabletask-js";
+ *
  * const timeoutTask = context.createTimer(expirationDate);
  * const workTask = context.callActivity("DoWork");
- * const winner = yield context.whenAny([timeoutTask, workTask]);
+ * const winner = yield whenAny([timeoutTask, workTask]);
  * if (winner === workTask && !timeoutTask.isCompleted) {
  *   timeoutTask.cancel();
  * }
@@ -44,6 +46,8 @@ export class TimerTask extends CompletableTask<undefined> {
    * pending `CreateTimer` action and pending-task entry, so this class needs no
    * knowledge of the context's internals.
    *
+   * @internal Invoked by the orchestration context when the timer is created.
+   *   Not part of the public `TimerTask` surface; orchestrator code must not call it.
    * @param handler - Called once, when {@link cancel} first transitions the timer
    *   to the canceled state.
    */

packages/durabletask-js/test/task.spec.ts

@@ -138,6 +138,14 @@ describe("Task (base class)", () => {
       expect(() => task.result).not.toThrow();
       expect(task.result).toBeUndefined();
     });
+
+    it("result returns undefined for a failed task even if _result was set", () => {
+      const t = new CompletableTask<string>();
+      t._result = "stale";
+      t.fail("boom");
+      expect(t.result).toBeUndefined();
+      expect(t.isFaulted).toBe(true);
+    });
   });
 
   describe("isCompleted / isFaulted (v3 aliases)", () => {