Merge pull request #6631 from Shopify/single_task_with_status_update

Refactor renderSingleTask to allow an async process to update current status

Author: nickwesselman

packages/cli-kit/bin/documentation/examples.ts

@@ -16,7 +16,7 @@ import {
   renderTextPrompt,
   renderWarning,
 } from '../../src/public/node/ui.js'
-import {unstyled} from '../../src/public/node/output.js'
+import {outputContent, unstyled} from '../../src/public/node/output.js'
 import {AbortError, BugError} from '../../src/public/node/error.js'
 import {AbortSignal} from '../../src/public/node/abort.js'
 import {Stdout} from '../../src/private/node/ui.js'
@@ -592,11 +592,12 @@ export const examples: {[key in string]: Example} = {
       const stdout = new Stdout({columns: TERMINAL_WIDTH})
 
       await renderSingleTask({
-        title: 'Loading app',
-        taskPromise: async () => {
+        title: outputContent`Loading app`,
+        task: async () => {
           await sleep(1)
         },
-      }, {renderOptions: {stdout: stdout as any, debug: true}})
+        renderOptions: {stdout: stdout as any, debug: true}
+      })
 
       // Find the last frame that includes mention of "Loading"
       const loadingFrame = stdout.frames.findLast(frame => frame.includes('Loading'))

packages/cli-kit/src/private/node/ui/components/SingleTask.test.tsx

@@ -1,19 +1,21 @@
 import {SingleTask} from './SingleTask.js'
 import {render} from '../../testing/ui.js'
+import {TokenizedString} from '../../../../public/node/output.js'
 import React from 'react'
 import {describe, expect, test} from 'vitest'
 
 describe('SingleTask', () => {
   test('unmounts when promise resolves successfully', async () => {
     // Given
-    const title = 'Uploading files'
+    const title = new TokenizedString('Uploading files')
     let resolvePromise: (value: string) => void
-    const taskPromise = new Promise<string>((resolve) => {
-      resolvePromise = resolve
-    })
+    const task = () =>
+      new Promise<string>((resolve) => {
+        resolvePromise = resolve
+      })
 
     // When
-    const renderInstance = render(<SingleTask title={title} taskPromise={taskPromise} />)
+    const renderInstance = render(<SingleTask title={title} task={task} />)
 
     // Wait for initial render
     await new Promise((resolve) => setTimeout(resolve, 10))
@@ -30,14 +32,15 @@ describe('SingleTask', () => {
 
   test('unmounts when promise rejects', async () => {
     // Given
-    const title = 'Failed task'
+    const title = new TokenizedString('Failed task')
     let rejectPromise: (error: Error) => void
-    const taskPromise = new Promise<string>((resolve, reject) => {
-      rejectPromise = reject
-    })
+    const task = () =>
+      new Promise<string>((resolve, reject) => {
+        rejectPromise = reject
+      })
 
     // When
-    const renderInstance = render(<SingleTask title={title} taskPromise={taskPromise} />)
+    const renderInstance = render(<SingleTask title={title} task={task} />)
 
     // Wait for initial render
     await new Promise((resolve) => setTimeout(resolve, 10))
@@ -51,11 +54,11 @@ describe('SingleTask', () => {
 
   test('handles promise that resolves immediately', async () => {
     // Given
-    const title = 'Instant task'
-    const taskPromise = Promise.resolve('immediate success')
+    const title = new TokenizedString('Instant task')
+    const task = () => Promise.resolve('immediate success')
 
     // When
-    const renderInstance = render(<SingleTask title={title} taskPromise={taskPromise} />)
+    const renderInstance = render(<SingleTask title={title} task={task} />)
     await renderInstance.waitUntilExit()
 
     // Then - component should complete successfully
@@ -64,51 +67,83 @@ describe('SingleTask', () => {
 
   test('handles promise that rejects immediately', async () => {
     // Given
-    const title = 'Instant failure'
-    const taskPromise = Promise.reject(new Error('Immediate error'))
+    const title = new TokenizedString('Instant failure')
+    const task = () => Promise.reject(new Error('Immediate error'))
 
     // When
-    const renderInstance = render(<SingleTask title={title} taskPromise={taskPromise} />)
+    const renderInstance = render(<SingleTask title={title} task={task} />)
 
     // Then - should exit with error
     await expect(renderInstance.waitUntilExit()).rejects.toThrow('Immediate error')
   })
 
   test('handles different types of promise return values', async () => {
     // Test with string
-    const stringTask = Promise.resolve('task completed')
-    const stringRender = render(<SingleTask title="String task" taskPromise={stringTask} />)
+    let stringResult: string | undefined
+    const stringTask = () => Promise.resolve('task completed')
+    const stringRender = render(
+      <SingleTask
+        title={new TokenizedString('String task')}
+        task={stringTask}
+        onComplete={(result) => (stringResult = result)}
+      />,
+    )
     await stringRender.waitUntilExit()
     expect(stringRender.lastFrame()).toBeDefined()
+    expect(stringResult).toBe('task completed')
 
     // Test with object
-    const objectTask = Promise.resolve({id: 1, name: 'test'})
-    const objectRender = render(<SingleTask title="Object task" taskPromise={objectTask} />)
+    let objectResult: {id: number; name: string} | undefined
+    const objectTask = () => Promise.resolve({id: 1, name: 'test'})
+    const objectRender = render(
+      <SingleTask
+        title={new TokenizedString('Object task')}
+        task={objectTask}
+        onComplete={(result) => (objectResult = result)}
+      />,
+    )
     await objectRender.waitUntilExit()
     expect(objectRender.lastFrame()).toBeDefined()
 
     // Test with number
-    const numberTask = Promise.resolve(42)
-    const numberRender = render(<SingleTask title="Number task" taskPromise={numberTask} />)
+    let numberResult: number | undefined
+    const numberTask = () => Promise.resolve(42)
+    const numberRender = render(
+      <SingleTask
+        title={new TokenizedString('Number task')}
+        task={numberTask}
+        onComplete={(result) => (numberResult = result)}
+      />,
+    )
     await numberRender.waitUntilExit()
     expect(numberRender.lastFrame()).toBeDefined()
+    expect(numberResult).toBe(42)
 
     // Test with boolean
-    const booleanTask = Promise.resolve(true)
-    const booleanRender = render(<SingleTask title="Boolean task" taskPromise={booleanTask} />)
+    let booleanResult: boolean | undefined
+    const booleanTask = () => Promise.resolve(true)
+    const booleanRender = render(
+      <SingleTask
+        title={new TokenizedString('Boolean task')}
+        task={booleanTask}
+        onComplete={(result) => (booleanResult = result)}
+      />,
+    )
     await booleanRender.waitUntilExit()
     expect(booleanRender.lastFrame()).toBeDefined()
+    expect(booleanResult).toBe(true)
   })
 
   test('handles promise with delayed resolution', async () => {
     // Given
-    const title = 'Delayed task'
-    const taskPromise = new Promise<string>((resolve) => {
-      setTimeout(() => resolve('completed'), 100)
-    })
+    const title = new TokenizedString('Delayed task')
+    const task = () =>
+      new Promise<string>((resolve) => {
+        setTimeout(() => resolve('completed'), 100)
+      })
 
     // When
-    const renderInstance = render(<SingleTask title={title} taskPromise={taskPromise} />)
+    const renderInstance = render(<SingleTask title={title} task={task} />)
 
     // Wait for completion
     await renderInstance.waitUntilExit()
@@ -119,13 +154,14 @@ describe('SingleTask', () => {
 
   test('handles promise with delayed rejection', async () => {
     // Given
-    const title = 'Delayed failure'
-    const taskPromise = new Promise<string>((resolve, reject) => {
-      setTimeout(() => reject(new Error('delayed error')), 100)
-    })
+    const title = new TokenizedString('Delayed failure')
+    const task = () =>
+      new Promise<string>((resolve, reject) => {
+        setTimeout(() => reject(new Error('delayed error')), 100)
+      })
 
     // When
-    const renderInstance = render(<SingleTask title={title} taskPromise={taskPromise} />)
+    const renderInstance = render(<SingleTask title={title} task={task} />)
 
     // Wait for completion - should throw error
     await expect(renderInstance.waitUntilExit()).rejects.toThrow('delayed error')
@@ -141,23 +177,23 @@ describe('SingleTask', () => {
     }
 
     const customError = new CustomError('Custom error message', 'CUSTOM_CODE')
-    const taskPromise = Promise.reject(customError)
+    const task = () => Promise.reject(customError)
 
     // When
-    const renderInstance = render(<SingleTask title="Custom error task" taskPromise={taskPromise} />)
+    const renderInstance = render(<SingleTask title={new TokenizedString('Custom error task')} task={task} />)
 
     // Then - should preserve the exact error
     await expect(renderInstance.waitUntilExit()).rejects.toThrow('Custom error message')
   })
 
   test('handles concurrent promise operations', async () => {
     // Given - Multiple SingleTask components with different promises
-    const fastPromise = new Promise((resolve) => setTimeout(() => resolve('fast'), 50))
-    const slowPromise = new Promise((resolve) => setTimeout(() => resolve('slow'), 150))
+    const fastPromise = () => new Promise((resolve) => setTimeout(() => resolve('fast'), 50))
+    const slowPromise = () => new Promise((resolve) => setTimeout(() => resolve('slow'), 150))
 
     // When
-    const fastRender = render(<SingleTask title="Fast task" taskPromise={fastPromise} />)
-    const slowRender = render(<SingleTask title="Slow task" taskPromise={slowPromise} />)
+    const fastRender = render(<SingleTask title={new TokenizedString('Fast task')} task={fastPromise} />)
+    const slowRender = render(<SingleTask title={new TokenizedString('Slow task')} task={slowPromise} />)
 
     // Then - Both should complete successfully
     await fastRender.waitUntilExit()
@@ -169,14 +205,69 @@ describe('SingleTask', () => {
 
   test('passes noColor prop to LoadingBar component', async () => {
     // Given
-    const title = 'No color task'
-    const taskPromise = Promise.resolve()
+    const title = new TokenizedString('No color task')
+    const task = () => Promise.resolve()
 
     // When - Test that noColor prop doesn't break the component
-    const renderInstance = render(<SingleTask title={title} taskPromise={taskPromise} noColor />)
+    const renderInstance = render(<SingleTask title={title} task={task} noColor />)
     await renderInstance.waitUntilExit()
 
     // Then - Component should complete successfully with noColor prop
     expect(renderInstance.lastFrame()).toBeDefined()
   })
+
+  test('updates status message during task execution', async () => {
+    // Given
+    const initialTitle = new TokenizedString('Starting task')
+    let step1Resolve: () => void
+    let step2Resolve: () => void
+    let step3Resolve: () => void
+
+    const step1Promise = new Promise<void>((resolve) => {
+      step1Resolve = resolve
+    })
+    const step2Promise = new Promise<void>((resolve) => {
+      step2Resolve = resolve
+    })
+    const step3Promise = new Promise<void>((resolve) => {
+      step3Resolve = resolve
+    })
+
+    const task = async (updateStatus: (status: TokenizedString) => void) => {
+      updateStatus(new TokenizedString('Running (1 complete)...'))
+      await step1Promise
+
+      updateStatus(new TokenizedString('Running (2 complete)...'))
+      await step2Promise
+
+      updateStatus(new TokenizedString('Running (3 complete)...'))
+      await step3Promise
+
+      return 'completed'
+    }
+
+    // When
+    const renderInstance = render(<SingleTask title={initialTitle} task={task} />)
+
+    // Wait for component to render with first status
+    await new Promise((resolve) => setTimeout(resolve, 10))
+    const frame1 = renderInstance.lastFrame()
+    expect(frame1).toContain('1 complete')
+
+    // Progress to step 2
+    step1Resolve!()
+    await new Promise((resolve) => setTimeout(resolve, 10))
+    const frame2 = renderInstance.lastFrame()
+    expect(frame2).toContain('2 complete')
+
+    // Progress to step 3
+    step2Resolve!()
+    await new Promise((resolve) => setTimeout(resolve, 10))
+    const frame3 = renderInstance.lastFrame()
+    expect(frame3).toContain('3 complete')
+
+    // Complete the task
+    step3Resolve!()
+    await renderInstance.waitUntilExit()
+  })
 })

packages/cli-kit/src/private/node/ui/components/SingleTask.tsx

@@ -1,37 +1,41 @@
 import {LoadingBar} from './LoadingBar.js'
 import {useExitOnCtrlC} from '../hooks/use-exit-on-ctrl-c.js'
+import {TokenizedString} from '../../../../public/node/output.js'
 import React, {useEffect, useState} from 'react'
 import {useApp} from 'ink'
 
-interface SingleTaskProps {
-  title: string
-  taskPromise: Promise<unknown>
+interface SingleTaskProps<T> {
+  title: TokenizedString
+  task: (updateStatus: (status: TokenizedString) => void) => Promise<T>
+  onComplete?: (result: T) => void
   noColor?: boolean
 }
 
-const SingleTask = ({taskPromise, title, noColor}: React.PropsWithChildren<SingleTaskProps>) => {
+const SingleTask = <T,>({task, title, onComplete, noColor}: SingleTaskProps<T>) => {
+  const [status, setStatus] = useState(title)
   const [isDone, setIsDone] = useState(false)
   const {exit: unmountInk} = useApp()
   useExitOnCtrlC()
 
   useEffect(() => {
-    taskPromise
-      .then(() => {
+    task(setStatus)
+      .then((result) => {
         setIsDone(true)
+        onComplete?.(result)
         unmountInk()
       })
       .catch((error) => {
         setIsDone(true)
         unmountInk(error)
       })
-  }, [taskPromise, unmountInk])
+  }, [task, unmountInk, onComplete])
 
   if (isDone) {
     // clear things once done
     return null
   }
 
-  return <LoadingBar title={title} noColor={noColor} />
+  return <LoadingBar title={status.value} noColor={noColor} />
 }
 
 export {SingleTask}