@hyperfrontend/workspace/progressprogress
The stages of a run and the view of it, as the command line shows them: which tasks run before which, where a failure stops the run, and what a terminal is shown while it goes.
What the command line shows of a run is built from parts that know nothing of how a task is executed, so a runner of your own can show the same thing.
assignStages gives every task the first stage that names its target and moves a prerequisite to the earliest stage that needs it. runStages runs the stages in order through a function you supply and stops after the first that did not succeed whole, answering the tasks that never started.
createProgressView writes a line as each task ends, the excerpt of a failed task's log from failureExcerpt, a sign of life for a task that runs long, and at the end the matrix of matrixLines with the totals. It writes through a Terminal from createTerminal, which rewrites a status line on a terminal and writes plain lines everywhere else.
import { assignStages, createProgressView, createTerminal, Ending, runStages } from '@hyperfrontend/workspace/progress'
const tasks = [
{ id: 'lib-core:lint', project: 'lib-core', target: 'lint', needs: [] },
{ id: 'lib-core:test', project: 'lib-core', target: 'test', needs: [] },
]
const stages = [['lint'], ['test']]
const stageOf = assignStages(tasks, stages)
const view = createProgressView({
tasks: tasks.map((task) => ({ ...task, stage: stageOf.get(task.id) ?? 0 })),
stages: stages.length,
terminal: createTerminal(process.stderr, process.env),
now: Date.now,
})
const { stopped } = await runStages({
tasks,
stageOf,
runStage: async (members, stage) => {
view.stage(stage)
for (const task of members) {
view.started(task.id)
view.ended({
id: task.id,
ending: Ending.Passed,
durationMs: 1200,
detail: null,
excerpt: null,
log: null,
})
}
return true
},
})
view.finish(stopped)API Reference§
ƒ Functions
Parameters
Returns
Map< string, number>Example
A build one test needs runs with the tests, the other builds after them
import { assignStages } from '@hyperfrontend/workspace/progress'
assignStages(
[
{ id: 'lib-core:build', target: 'build', needs: [] },
{ id: 'lib-core:test', target: 'test', needs: ['lib-core:build'] },
{ id: 'lib-util:lint', target: 'lint', needs: [] },
{ id: 'lib-util:build', target: 'build', needs: [] },
],
[['typecheck', 'lint'], ['test'], ['build']]
)
// => Map { 'lib-core:build' => 1, 'lib-core:test' => 1, 'lib-util:lint' => 0, 'lib-util:build' => 2 }Parameters
| Name | Type | Description |
|---|---|---|
§options | ViewOptions | The tasks, the stages, where to write and the clock |
Returns
ProgressViewExample
One task that fails, and what the run ends on
import { createProgressView, createTerminal, Ending } from '@hyperfrontend/workspace/progress'
const view = createProgressView({
tasks: [
{ id: 'lib-core:lint', project: 'lib-core', target: 'lint', stage: 0 },
{ id: 'lib-core:test', project: 'lib-core', target: 'test', stage: 1 },
],
stages: 2,
terminal: createTerminal(process.stderr, process.env),
now: Date.now,
})
view.stage(0)
view.started('lib-core:lint')
view.ended({
id: 'lib-core:lint',
ending: Ending.Failed,
durationMs: 4200,
detail: null,
excerpt: 'src/index.ts:3:1 error no-default-export',
log: '.hf/logs/lib-core__lint.log',
})
view.finish(0)
// stage 1 of 2: lint (1 task)
// ✗ lib-core:lint 4.2s [1/2]
// src/index.ts:3:1 error no-default-export
// log: .hf/logs/lib-core__lint.log
// stage 1 (lint) did not succeed: 1 task not run
//
// lint test
// lib-core ✗ ·
// ✓ passed ✗ failed - skipped · not run
//
// 2 tasks in 4.2s: 1 failed, 1 not run
// ✗ lib-core:lint .hf/logs/lib-core__lint.logcreateTerminal( sink: ProgressSink, env: Readonly< Record< string, string | undefined>>): Terminal
Parameters
| Name | Type | Description |
|---|---|---|
§sink | ProgressSink | The stream written to |
§env | Readonly< | The environment: NO_COLOR set to anything, or a TERM of dumb, asks for plain output |
Returns
TerminalExample
A stream that is not a terminal gets plain lines and no status
import { createTerminal, Style } from '@hyperfrontend/workspace/progress'
const terminal = createTerminal(process.stderr, process.env)
terminal.status('lib-core:build 42s')
terminal.line(`${terminal.paint('✓', Style.Green)} lib-core:build`)
// through a pipe: writes '✓ lib-core:build\n' and nothing for the statusParameters
Returns
stringExample
The end of the output, unless the test runner listed its failing tests
import { failureExcerpt } from '@hyperfrontend/workspace/progress'
failureExcerpt('one\ntwo\nthree\n', 2) // => 'two\nthree'
failureExcerpt('✔ passes\n✖ failing tests:\n✖ breaks\nfile | line %') // => '✖ failing tests:\n✖ breaks'
failureExcerpt('') // => nullParameters
| Name | Type | Description |
|---|---|---|
§ms | number | Milliseconds |
Returns
stringExample
Tenths under ten seconds, whole seconds under a minute
import { formatDuration } from '@hyperfrontend/workspace/progress'
formatDuration(800) // => '0.8s'
formatDuration(47_000) // => '47s'
formatDuration(1_097_000) // => '18m 17s'Parameters
Returns
stringExample
The same marks lead a task's line and fill the matrix
import { createTerminal, Ending, markOf } from '@hyperfrontend/workspace/progress'
markOf(Ending.Failed, createTerminal(process.stderr, process.env).paint) // => '✗', red on a terminalParameters
Returns
string[ ]Example
A failed type check that kept the build from running
import { createTerminal, Ending, matrixLines } from '@hyperfrontend/workspace/progress'
matrixLines(
[
{ project: 'lib-core', target: 'typecheck', stage: 0, ending: Ending.Failed },
{ project: 'lib-core', target: 'build', stage: 1, ending: Ending.NotRun },
{ project: 'lib-util', target: 'typecheck', stage: 0, ending: Ending.Passed },
],
createTerminal(process.stderr, process.env).paint
)
// => [
// ' typecheck build',
// 'lib-core ✗ ·',
// 'lib-util ✓',
// '✓ passed ✗ failed - skipped · not run',
// ]Parameters
| Name | Type | Description |
|---|---|---|
§options | StagedOptions< | The tasks, the stage of each and how one stage runs |
Example
A failed first stage keeps the second from starting
import { runStages } from '@hyperfrontend/workspace/progress'
const tasks = [{ id: 'lib-core:lint' }, { id: 'lib-core:test' }]
const stageOf = new Map([
['lib-core:lint', 0],
['lib-core:test', 1],
])
await runStages({ tasks, stageOf, runStage: async (stage) => stage.every((task) => task.id !== 'lib-core:lint') })
// => { stopped: 0, notRun: ['lib-core:test'] }Parameters
Returns
stringExample
The colon of a task id never reaches a file name
import { taskLogPath } from '@hyperfrontend/workspace/progress'
taskLogPath('lib-core:build', '.hf/logs') // => '.hf/logs/lib-core__build.log'◈ Interfaces
Properties
Properties
Properties
Properties
Properties
Properties
Properties
readonly detail:stringWhy it did not run or did not reach an exit, shown in place of the duration, or null.Properties
readonly plain:booleanWhether the output takes plain lines alone: no colour, and no line rewritten in place.readonly line:( text: string) => voidWrites a finished line, in place of the status when one is shown.readonly status:( text: string) => voidShows a status the next line or status replaces; writes nothing on plain output.