Remove @ts-expect-error and add some documentation

Author: pombosilva

packages/vitest-pool-workers/src/worker/workflows.ts

@@ -4,6 +4,7 @@ import {
 } from "@cloudflare/workflows-shared/src/instance";
 import { runInRunnerObject } from "./durable-objects";
 import { env, internalEnv } from "./env";
+import type { WorkflowBinding } from "@cloudflare/workflows-shared/src/binding";
 import type {
 	StepSelector,
 	WorkflowInstanceModifier,
@@ -23,7 +24,7 @@ export interface WorkflowInstanceIntrospector {
 }
 
 export async function introspectWorkflowInstance(
-	workflow: Workflow,
+	workflow: WorkflowBinding,
 	instanceId: string
 ): Promise<WorkflowInstanceIntrospector> {
 	if (!workflow || !instanceId) {
@@ -37,15 +38,17 @@ export async function introspectWorkflowInstance(
 class WorkflowInstanceIntrospectorHandle
 	implements WorkflowInstanceIntrospector
 {
-	#workflow: Workflow;
+	#workflow: WorkflowBinding;
 	#instanceId: string;
 	#instanceModifier: WorkflowInstanceModifier;
 
-	constructor(workflow: Workflow, instanceId: string) {
+	constructor(workflow: WorkflowBinding, instanceId: string) {
 		this.#workflow = workflow;
 		this.#instanceId = instanceId;
-		// @ts-expect-error not exposed
-		this.#instanceModifier = workflow.unsafeGetInstanceModifier(instanceId);
+
+		this.#instanceModifier = workflow.unsafeGetInstanceModifier(
+			instanceId
+		) as WorkflowInstanceModifier;
 	}
 
 	async modify(fn: ModifierCallback): Promise<WorkflowInstanceIntrospector> {
@@ -55,7 +58,6 @@ class WorkflowInstanceIntrospectorHandle
 	}
 
 	async waitForStepResult(step: StepSelector): Promise<unknown> {
-		// @ts-expect-error not exposed
 		const stepResult = await this.#workflow.unsafeWaitForStepResult(
 			this.#instanceId,
 			step.name,
@@ -80,12 +82,10 @@ class WorkflowInstanceIntrospectorHandle
 			// starts running, so waiting for it to be queued should always return
 			return;
 		}
-		// @ts-expect-error not exposed
 		await this.#workflow.unsafeWaitForStatus(this.#instanceId, status);
 	}
 
 	async cleanUp(): Promise<void> {
-		// @ts-expect-error not exposed
 		await this.#workflow.unsafeAbort(this.#instanceId, "Instance clean up");
 	}
 
@@ -104,15 +104,15 @@ export interface WorkflowIntrospector {
 }
 
 export async function introspectWorkflow(
-	workflow: Workflow
+	workflow: WorkflowBinding
 ): Promise<WorkflowIntrospectorHandle> {
 	if (!workflow) {
 		throw new Error("[WorkflowIntrospector] Workflow binding is required.");
 	}
 
 	const modifierCallbacks: ModifierCallback[] = [];
 	const instanceIntrospectors: WorkflowInstanceIntrospector[] = [];
-	// @ts-expect-error getBindingName not exposed
+
 	const bindingName = await workflow.unsafeGetBindingName();
 	const internalOriginalWorkflow = internalEnv[bindingName] as Workflow;
 	const externalOriginalWorkflow = env[bindingName] as Workflow;
@@ -214,13 +214,13 @@ export async function introspectWorkflow(
 }
 
 class WorkflowIntrospectorHandle implements WorkflowIntrospector {
-	workflow: Workflow;
+	workflow: WorkflowBinding;
 	#modifierCallbacks: ModifierCallback[];
 	#instanceIntrospectors: WorkflowInstanceIntrospector[];
 	#cleanupCallback: () => void;
 
 	constructor(
-		workflow: Workflow,
+		workflow: WorkflowBinding,
 		modifierCallbacks: ModifierCallback[],
 		instanceIntrospectors: WorkflowInstanceIntrospector[],
 		cleanupCallback: () => void

packages/workflows-shared/src/modifier.ts

@@ -76,6 +76,12 @@ export class WorkflowInstanceModifier extends RpcTarget {
 		}
 	}
 
+	// step.do() flow: It first checks if a result or error is already in the cache and, if so, returns it immediately.
+	// If nothing is in the cache, it checks for remaining attempts and runs the user's code against the defined timeout.
+	// Since `step.do()` performs this initial cache check, directly changing the `valueKey` would cause it to
+	// assume the value was pre-cached, preventing it from writing any logs about the step's execution state.
+	// Storing the value under a separate key is crucial because it ensures all execution logs for the step are
+	// generated, rather than the step being skipped due to a premature cache hit.
 	async mockStepResult(step: StepSelector, stepResult: unknown): Promise<void> {
 		const valueKey = await this.#getStepCacheKey(step);
 
@@ -88,6 +94,7 @@ export class WorkflowInstanceModifier extends RpcTarget {
 		await this.#state.storage.put(`replace-result-${valueKey}`, stepResult);
 	}
 
+	// Same logic of `mockStepResult` but stores an error instead of a value.
 	async mockStepError(
 		step: StepSelector,
 		error: Error,