console-toolkit 1.0.0

package/src/charts/bars/plain.js

@@ -0,0 +1,63 @@
+import style from '../../style.js';
+import {optimize} from '../../ansi/sgr-state.js';
+import {allocateSizes, makeBgFromFg} from '../utils.js';
+import drawStackedChart from './draw-stacked.js';
+import {vBlocks8th, ellipsis} from '../../symbols.js';
+import defaultTheme from '../themes/default.js';
+
+// data = [datum]
+// datum = {value, colorState, symbol, state}
+
+const defaultSymbol = vBlocks8th[7];
+
+export const defaultDrawItem = (datum, size, _, {initState = {}}) =>
+  datum
+    ? style
+        .addState(initState)
+        .addState(datum.colorState || {})
+        .addState(datum.state || {})
+        .text((datum.symbol || defaultSymbol).repeat(size))
+    : '';
+
+export const drawItemLabel = (datum, size, _, {reverse, truncate, useEllipsis = true, initState = {}}) => {
+  if (!datum) return '';
+  const symbol = datum.symbol || ' ';
+  let label = datum.label || '';
+  if (label.length <= size) {
+    label = reverse ? label.padStart(size, symbol) : label.padEnd(size, symbol);
+  } else if (truncate && (!useEllipsis || size > 1)) {
+    label = useEllipsis ? label.substring(0, size - 1) + ellipsis : label.substring(0, size);
+  } else {
+    label = symbol.repeat(size);
+  }
+  return style
+    .addState(initState)
+    .addState(datum.colorState ? makeBgFromFg(datum.colorState) : {})
+    .addState(datum.state || {})
+    .text(label);
+};
+
+export const drawRow = (data, width, maxValue, options = {}) => {
+  const {drawItem = defaultDrawItem, rectSize = 0, theme = defaultTheme, initState, reverse} = options,
+    {symbol = ' ', state = null, colorState} = theme?.empty || {},
+    sizes = allocateSizes(data, maxValue, width),
+    items = data.map((datum, index) => drawItem(datum, sizes[index], {index, data, sizes, maxValue, width}, options));
+  if (theme?.empty && sizes[sizes.length - 1] > 0) {
+    // fill the row
+    items.push(
+      style
+        .addState(initState)
+        .addState(colorState)
+        .addState(state)
+        .text(symbol.repeat(sizes[sizes.length - 1]))
+    );
+  }
+  if (reverse) items.reverse();
+  const row = optimize(items.join(''));
+  if (rectSize <= 1) return row;
+  return new Array(rectSize).fill(row);
+};
+
+export const drawChart = drawStackedChart(drawRow);
+
+export default drawChart;

package/src/charts/columns/block-frac-grouped.js

@@ -0,0 +1,6 @@
+import {drawColumn} from './block-frac.js';
+import drawGroupedChart from './draw-grouped.js';
+
+export const drawChart = drawGroupedChart(drawColumn);
+
+export default drawChart;

package/src/charts/columns/block-frac.js

@@ -0,0 +1,30 @@
+import style from '../../style.js';
+import Box from '../../box.js';
+import {optimize} from '../../ansi/sgr-state.js';
+import {allocateSizes} from '../utils.js';
+import drawStackedChart from './draw-stacked.js';
+import {drawRealWidthBlock} from '../../draw-block-frac.js';
+
+// data = [datum]
+// datum = {value, colorState, symbol, state}
+
+export const drawColumn = (data, width, maxValue, options = {}) => {
+  const {reverse, drawEmptyBorder, initState} = options,
+    rectSize = Math.max(0, options.rectSize ?? 0.5),
+    sizes = allocateSizes(data, maxValue, width),
+    blocks = data.map((datum, i) => {
+      if (!datum) return Box.makeBlank(/*getFracSize(rectSize, drawEmptyBorder)*/ 0, 0);
+      const box = drawRealWidthBlock(rectSize, sizes[i], drawEmptyBorder),
+        boxStyle = style.addState(initState).addState(datum.colorState).addState(datum.state);
+      return new Box(
+        box.box.map(line => boxStyle.text(line)),
+        true
+      );
+    }),
+    result = (reverse ? blocks : blocks.reverse()).map(block => block.box).flat(1);
+  return result.map(line => optimize(line));
+};
+
+export const drawChart = drawStackedChart(drawColumn);
+
+export default drawChart;

package/src/charts/columns/block-grouped.js

@@ -0,0 +1,6 @@
+import {drawColumn} from './block.js';
+import drawGroupedChart from './draw-grouped.js';
+
+export const drawChart = drawGroupedChart(drawColumn);
+
+export default drawChart;

package/src/charts/columns/block.js

@@ -0,0 +1,37 @@
+import style from '../../style.js';
+import Box from '../../box.js';
+import {optimize} from '../../ansi/sgr-state.js';
+import {allocateSizes} from '../utils.js';
+import drawStackedChart from './draw-stacked.js';
+import drawBlock from '../../draw-block.js';
+import defaultBlockTheme from '../../themes/blocks/unicode-half.js';
+
+// data = [datum]
+// datum = {value, colorState, symbol, state}
+
+export const drawColumn = (data, width, maxValue, options = {}) => {
+  const {reverse, blockTheme = defaultBlockTheme, rectSize = 0, initState = {}} = options,
+    sizes = allocateSizes(data, maxValue, width),
+    {t = reverse ? 0 : 1, b = reverse ? 1 : 0, l = 1, r = 1} = options;
+
+  const blocks = data.map((datum, i) => {
+      if (!datum) return Box.makeBlank(Math.max(2, rectSize), 0);
+      const box = drawBlock(Math.max(0, rectSize - 2), sizes[i], blockTheme, {
+          bottom: reverse ? (i + 1 < data.length ? 0 : b) : i ? 0 : b,
+          top: reverse ? (i ? 0 : t) : i + 1 < data.length ? 0 : t,
+          left: l,
+          right: r
+        }),
+        boxStyle = style.addState(initState).addState(datum.colorState).addState(datum.state);
+      return new Box(
+        box.box.map(line => boxStyle.text(line)),
+        true
+      );
+    }),
+    result = (reverse ? blocks : blocks.reverse()).map(block => block.box).flat(1);
+  return result.map(line => optimize(line));
+};
+
+export const drawChart = drawStackedChart(drawColumn);
+
+export default drawChart;

package/src/charts/columns/draw-grouped.js

@@ -0,0 +1,48 @@
+import defaultTheme from '../themes/default.js';
+import {normalizeData} from '../utils.js';
+import Panel from '../../panel.js';
+import style from '../../style.js';
+
+export const drawChart =
+  drawColumn =>
+  (values, width, options = {}) => {
+    const {maxValue, reverse, initState, groupGap = 1, gap = 0, theme = defaultTheme} = options;
+    if (isNaN(width) || width <= 0) throw new Error(`"width" should be a positive integer instead of "${width}"`);
+
+    const data = normalizeData(values, theme),
+      maxSeriesLength = Math.max(0, ...data.map(series => series.length));
+
+    // normalize length of series and flatten the result
+    const newData = [];
+    data.forEach(series => {
+      newData.push(...series);
+      if (series.length < maxSeriesLength) newData.push(...new Array(maxSeriesLength - series.length).fill(null));
+    });
+
+    const max =
+        typeof maxValue == 'number' && maxValue >= 0
+          ? maxValue
+          : Math.max(0, ...newData.map(datum => datum?.value || 0)),
+      {symbol = ' ', state = null, colorState} = theme?.empty || {},
+      emptyState = style.addState(initState).addState(colorState).addState(state).getState();
+
+    const panel = new Panel(0, width);
+    for (let i = 0; i < newData.length; ++i) {
+      if (i) {
+        if (i % maxSeriesLength == 0) {
+          if (groupGap > 0) panel.padRight(groupGap);
+        } else {
+          if (gap > 0) panel.padRight(gap);
+        }
+      }
+      const p = Panel.make(drawColumn([newData[i]], width, max, options));
+      if (p) {
+        panel.addRight(p, {align: reverse ? 'top' : 'bottom'});
+      } else {
+        panel.padRight(1);
+      }
+    }
+    return panel.toBox({emptySymbol: symbol, emptyState}).box;
+  };
+
+export default drawChart;

package/src/charts/columns/draw-stacked.js

@@ -0,0 +1,31 @@
+import defaultTheme from '../themes/default.js';
+import {normalizeData, sumValues} from '../utils.js';
+import Panel from '../../panel.js';
+import style from '../../style.js';
+
+export const drawChart =
+  drawColumn =>
+  (values, width, options = {}) => {
+    const {maxValue, reverse, initState, gap = 0, theme = defaultTheme} = options;
+    if (isNaN(width) || width <= 0) throw new Error(`"width" should be a positive integer instead of "${width}"`);
+
+    const data = normalizeData(values, theme),
+      max =
+        typeof maxValue == 'number' ? (maxValue < 0 ? -1 : maxValue) : Math.max(0, ...data.map(row => sumValues(row))),
+      {symbol = ' ', state = null, colorState} = theme?.empty || {},
+      emptyState = style.addState(initState).addState(colorState).addState(state).getState();
+
+    const panel = new Panel(0, width);
+    for (let i = 0; i < data.length; ++i) {
+      if (i && gap > 0) panel.padRight(gap);
+      const p = Panel.make(drawColumn(data[i], width, max, options));
+      if (p) {
+        panel.addRight(p, {align: reverse ? 'top' : 'bottom'});
+      } else {
+        panel.padRight(1);
+      }
+    }
+    return panel.toBox({emptySymbol: symbol, emptyState}).box;
+  };
+
+export default drawChart;

package/src/charts/columns/frac-grouped.js

@@ -0,0 +1,27 @@
+import style from '../../style.js';
+import Box from '../../box.js';
+import {optimize} from '../../ansi/sgr-state.js';
+import {drawRealHeightBlock} from '../../draw-block-frac.js';
+import drawGroupedChart from './draw-grouped.js';
+
+// data = [datum]
+// datum = {value, colorState, symbol, state}
+
+export const drawColumn = (data, width, maxValue, options = {}) => {
+  const {reverse, rectSize = 1, initState = {}} = options,
+    blocks = data.map(datum => {
+      if (!datum) return Box.makeBlank(rectSize, 0);
+      const box = drawRealHeightBlock(rectSize, (datum.value / maxValue) * width),
+        boxStyle = style.addState(initState).addState(datum.colorState).addState(datum.state);
+      return new Box(
+        box.box.map(line => boxStyle.text(line)),
+        true
+      );
+    }),
+    result = (reverse ? blocks : blocks.reverse()).map(block => block.box).flat(1);
+  return result.map(line => optimize(line));
+};
+
+export const drawChart = drawGroupedChart(drawColumn);
+
+export default drawChart;

package/src/charts/columns/plain-grouped.js

@@ -0,0 +1,6 @@
+import {drawColumn} from './plain.js';
+import drawGroupedChart from './draw-grouped.js';
+
+export const drawChart = drawGroupedChart(drawColumn);
+
+export default drawChart;

package/src/charts/columns/plain.js

@@ -0,0 +1,39 @@
+import style from '../../style.js';
+import Box from '../../box.js';
+import {optimize} from '../../ansi/sgr-state.js';
+import {allocateSizes} from '../utils.js';
+import drawStackedChart from './draw-stacked.js';
+import {hBlocks8th} from '../../symbols.js';
+import defaultTheme from '../themes/default.js';
+
+// data = [datum]
+// datum = {value, colorState, symbol, state}
+
+const defaultSymbol = hBlocks8th[7];
+
+export const drawColumn = (data, width, maxValue, options = {}) => {
+  const {reverse, rectSize = 1, initState = {}, theme = defaultTheme} = options,
+    {symbol = ' ', state = null, colorState} = theme?.empty || {},
+    sizes = allocateSizes(data, maxValue, width),
+    blocks = data.map((datum, i) => {
+      if (!datum) return Box.makeBlank(rectSize, 0);
+      const boxStyle = style.addState(initState).addState(datum.colorState).addState(datum.state);
+      return new Box(new Array(sizes[i]).fill(boxStyle.text(datum.symbol || defaultSymbol)), true);
+    });
+  if (sizes[sizes.length - 1] > 0) {
+    blocks.push(
+      new Box(
+        new Array(sizes[sizes.length - 1]).fill(
+          style.addState(initState).addState(colorState).addState(state).text(symbol.repeat(rectSize))
+        ),
+        true
+      )
+    );
+  }
+  const result = (reverse ? blocks : blocks.reverse()).map(block => block.box).flat(1);
+  return result.map(line => optimize(line));
+};
+
+export const drawChart = drawStackedChart(drawColumn);
+
+export default drawChart;

package/src/charts/themes/default.js

@@ -0,0 +1,12 @@
+import {capitalize} from '../../meta.js';
+import style from '../../style.js';
+
+const seriesColors = 'cyan,magenta,blue,yellow,green,red'.split(',');
+
+export const chartTheme = [
+  ...seriesColors.map(name => ({colorState: style['bright' + capitalize(name)].getState()})),
+  ...seriesColors.map(name => ({colorState: style[name].getState()}))
+];
+chartTheme.empty = {state: style.reset.all.getState(), symbol: ' '};
+
+export default chartTheme;

package/src/charts/themes/rainbow-reversed.js

@@ -0,0 +1,5 @@
+import rainbow from "./rainbow.js";
+
+export const chartTheme = rainbow.slice().reverse();
+
+export default chartTheme;

package/src/charts/themes/rainbow.js

@@ -0,0 +1,8 @@
+import style from '../../style.js';
+
+// red, orange, yellow, green, blue, indigo, violet
+const colors = [0xff0000, 0xffa500, 0xffff00, 0x008000, 0x0000ff, 0x4b0082, 0xee82ee];
+
+export const chartTheme = colors.map(color => ({colorState: style.hex(color).getState()}));
+
+export default chartTheme;

package/src/charts/utils.js

@@ -0,0 +1,75 @@
+import {Commands} from '../ansi/sgr.js';
+import defaultTheme from './themes/default.js';
+
+export const makeBgFromFg = state => ({
+  background: !state.foreground
+    ? null
+    : Array.isArray(state.foreground)
+    ? [Commands.BG_EXTENDED_COLOR, ...state.foreground.slice(1)]
+    : Number(state.foreground) + 10
+});
+
+export const makeFgFromBg = state => ({
+  foreground: !state.background
+    ? null
+    : Array.isArray(state.background)
+    ? [Commands.EXTENDED_COLOR, ...state.background.slice(1)]
+    : Number(state.background) - 10
+});
+
+export const sumValues = series => series.reduce((acc, datum) => acc + (datum?.value || 0), 0);
+
+export const normalizeData = (data, theme) =>
+  data.map(series => {
+    if (!Array.isArray(series)) series = [series];
+    return series.map((datum, i) => {
+      if (typeof datum == 'number') datum = {value: datum};
+      const value = Math.max(0, datum?.value ?? 0),
+        defaultSeriesTheme = defaultTheme[i % defaultTheme.length],
+        seriesTheme = theme[i % theme.length];
+      return {...defaultSeriesTheme, ...seriesTheme, ...datum, value: isNaN(value) || value < 0 ? 0 : value};
+    });
+  });
+
+export const allocateSizes = (data, maxValue, size) => {
+  const values = data.map((datum, index) => ({value: datum?.value || 0, index})),
+    seriesValue = values.reduce((acc, datum) => acc + datum.value, 0);
+
+  if (maxValue < 0) {
+    maxValue = seriesValue;
+    if (!maxValue) maxValue = 1;
+  }
+  if (seriesValue < maxValue) {
+    values.push({value: maxValue - seriesValue, index: -1}); // add an empty bin
+  } else {
+    // truncate values above maxValue
+    let acc = 0;
+    for (const datum of values) {
+      datum.value = acc < maxValue ? Math.min(datum.value, maxValue - acc) : 0;
+      acc += datum.value;
+    }
+  }
+
+  let allocated = 0;
+  values.forEach(datum => {
+    const allocation = (datum.value / maxValue) * size;
+    allocated += datum.size = Math.floor(allocation);
+    datum.frac = allocation - datum.size;
+  });
+
+  values.sort((a, b) => b.frac - a.frac);
+  for (let i = 0, n = size - allocated; i < n; ++i) ++values[i].size;
+
+  const sizes = new Array(data.length + 1).fill(0);
+  values.forEach(datum => (sizes[datum.index >= 0 ? datum.index : sizes.length - 1] = datum.size));
+  return sizes;
+};
+
+export const getFracSize = (value, drawEmptyBorder) => {
+  const intValue = Math.floor(value),
+    hasFrac = value - intValue > 0,
+    index = (value - intValue) * 8,
+    drawBorder = hasFrac && (drawEmptyBorder || index > 0);
+
+  return intValue + (drawBorder ? 1 : 0);
+};

package/src/draw-block-frac.js

@@ -0,0 +1,33 @@
+import {fullBlock, hBlocks8th, vBlocks8th} from './symbols.js';
+import Box from './box.js';
+
+export const drawRealWidthBlock = (realWidth, height, drawEmptyBorder) => {
+  realWidth = Math.max(0, realWidth);
+  height = Math.max(0, Math.floor(height));
+
+  const intWidth = Math.floor(realWidth),
+    index = Math.round((realWidth - intWidth) * 8),
+    hasFrac = realWidth - intWidth > 0,
+    drawBorder = hasFrac && (drawEmptyBorder || index > 0);
+
+  let line = fullBlock.repeat(intWidth);
+  if (drawBorder) line += hBlocks8th[index];
+  return new Box(new Array(height).fill(line), true);
+};
+
+export const drawRealHeightBlock = (width, realHeight, drawEmptyBorder) => {
+  width = Math.max(0, Math.floor(width));
+  realHeight = Math.max(0, realHeight);
+
+  const intHeight = Math.floor(realHeight),
+    index = Math.round((realHeight - intHeight) * 8),
+    hasFrac = realHeight - intHeight > 0,
+    drawBorder = hasFrac && (drawEmptyBorder || index > 0);
+
+  let result = fullBlock.repeat(intHeight);
+  if (drawBorder) result += hBlocks8th[index];
+  return new Box(
+    [...(drawBorder ? [vBlocks8th[index].repeat(width)] : []), ...new Array(intHeight).fill(fullBlock.repeat(width))],
+    true
+  );
+};

package/src/draw-block.js

@@ -0,0 +1,55 @@
+import Box from './box.js';
+
+const getIndex = (h, v) => 4 * h + v;
+
+const T = 1,
+  B = 2,
+  L = 1,
+  R = 2,
+  LT = getIndex(L, T),
+  RT = getIndex(R, T),
+  LB = getIndex(L, B),
+  RB = getIndex(R, B);
+
+export const drawBlock = (
+  width,
+  height,
+  blockTheme,
+  {top, bottom, left, right, vTheme, hTheme, theme, symbol} = {}
+) => {
+  // decode options
+  top ??= hTheme ?? theme ?? 1;
+  bottom ??= hTheme ?? theme ?? 1;
+  left ??= vTheme ?? theme ?? 1;
+  right ??= vTheme ?? theme ?? 1;
+  symbol ??= blockTheme?.f || ' ';
+
+  const topLine = top
+      ? (left ? blockTheme['t_' + top + '_' + left][LT] : '') +
+        blockTheme['h_' + top][T].repeat(width) +
+        (right ? blockTheme['t_' + top + '_' + right][RT] : '')
+      : null,
+    bottomLine = bottom
+      ? (left ? blockTheme['t_' + bottom + '_' + left][LB] : '') +
+        blockTheme['h_' + bottom][B].repeat(width) +
+        (right ? blockTheme['t_' + bottom + '_' + right][RB] : '')
+      : null,
+    middleLine =
+      (left ? blockTheme['v_' + left][L] : '') + symbol.repeat(width) + (right ? blockTheme['v_' + right][R] : '');
+
+  return new Box(
+    [
+      topLine === null ? [] : [topLine],
+      new Array(height).fill(middleLine),
+      bottomLine === null ? [] : [bottomLine]
+    ].flat(1),
+    true
+  );
+};
+
+export const drawFrame = (width, height, blockTheme, options) => {
+  if (!options?.symbol) options = {...options, symbol: ' '};
+  return drawBlock(width, height, blockTheme, options);
+}
+
+export default drawBlock;

package/src/meta.js

@@ -0,0 +1,41 @@
+export const capitalize = name => (name ? name[0].toUpperCase() + name.substring(1).toLowerCase() : name);
+
+export const toCamelCase = names =>
+  names.map((name, index) => (index ? capitalize(name) : name.toLowerCase())).join('');
+export const fromCamelCase = name => name.split(/(?=[A-Z])/g);
+
+export const toPascalCase = names => names.map(name => capitalize(name)).join('');
+export const fromPascalCase = name => name.split(/(?=[A-Z])/g);
+
+export const toAllCapsSnakeCase = names => names.map(name => name.toUpperCase()).join('_');
+export const toSnakeCase = names => names.map(name => name.toLowerCase()).join('_');
+export const fromSnakeCase = name => name.split('_');
+
+export const toKebabCase = names => names.map(name => name.toLowerCase()).join('-');
+export const fromKebabCase = name => name.split('-');
+
+export const addGetter = (Class, name, getter, force) => {
+  const object = Class.prototype || Class;
+  if (!force && object.hasOwnProperty(name)) return object;
+  return Object.defineProperty(object, name, {configurable: true, enumerable: true, get: getter});
+};
+
+export const addGetters = (Class, getters, force) => {
+  for (const [name, value] of Object.entries(getters)) {
+    addGetter(Class, name, value, force);
+  }
+};
+
+export const addAlias = (Class, name, oldName, force) => {
+  const object = Class.prototype || Class;
+  if (!force && object.hasOwnProperty(name)) return object;
+  const descriptor = Object.getOwnPropertyDescriptor(object, oldName);
+  if (!descriptor) return object;
+  return Object.defineProperty(object, name, descriptor);
+};
+
+export const addAliases = (Class, aliases, force) => {
+  for (const [name, oldName] of Object.entries(aliases)) {
+    addAlias(Class, name, oldName, force);
+  }
+};

package/src/output/show.js

@@ -0,0 +1,40 @@
+import process from 'node:process';
+import {matchCsiNoGroups} from '../strings.js';
+import Box from '../box.js';
+
+export const log = (s, {endOfLineCommand = '\x1B[m', colorDepth = 24} = {}) => {
+  s = Box.make(s);
+  if (colorDepth < 4) {
+    matchCsiNoGroups.lastIndex = 0;
+    s.box.forEach(row => console.log((row + endOfLineCommand).replace(matchCsiNoGroups, '')));
+    return;
+  }
+  s.box.forEach(row => console.log(row + endOfLineCommand));
+};
+
+export const out = (s, {stream = process.stdout, endOfLineCommand = '\x1B[m', colorDepth} = {}) => {
+  s = Box.make(s);
+  if (typeof colorDepth != 'number' || isNaN(colorDepth)) colorDepth = stream.isTTY ? stream.getColorDepth() : 1;
+  if (colorDepth < 4) {
+    matchCsiNoGroups.lastIndex = 0;
+    s.box.forEach(row => stream.write((row + endOfLineCommand).replace(matchCsiNoGroups, '') + '\n'));
+    return;
+  }
+  s.box.forEach(row => stream.write(row + endOfLineCommand + '\n'));
+};
+
+export class Out {
+  constructor(stream) {
+    this.stream = stream;
+    this.colorDepth = stream.isTTY ? stream.getColorDepth() : 1;
+  }
+  out(s, {endOfLineCommand = '\x1B[m', colorDepth} = {}) {
+    if (typeof colorDepth != 'number' || isNaN(colorDepth)) colorDepth = this.colorDepth;
+    return out(s, {stream: this.stream, endOfLineCommand, colorDepth});
+  }
+}
+
+export const debug = string =>
+  console.log(
+    string.replace(/[\x00-\x1F]/g, m => '\\x' + m[0].charCodeAt(0).toString(16).padStart(2, '0').toUpperCase())
+  );

package/src/output/updater.js

@@ -0,0 +1,82 @@
+'use strict';
+
+import Writer from './writer.js';
+import {toStrings} from '../strings.js';
+import {cursorUp, setCommands} from '../ansi/csi.js';
+
+const RESET = setCommands([]);
+
+export class Updater {
+  constructor(updater, {prologue, epilogue, noLastNewLine} = {}, writer = new Writer()) {
+    this.updater = updater;
+    this.writer = writer;
+    this.prologue = prologue || RESET;
+    this.epilogue = epilogue || RESET;
+    this.noLastNewLine = noLastNewLine;
+    this.lastHeight = 0;
+    this.isDone = false;
+    this.first = true;
+    this.intervalHandle = null;
+  }
+
+  get isRefreshing() {
+    return this.intervalHandle !== null;
+  }
+
+  startRefreshing(ms = 100) {
+    if (this.intervalHandle || this.isDone || !this.writer.isTTY) return;
+    this.intervalHandle = setInterval(this.update.bind(this), ms);
+  }
+
+  stopRefreshing() {
+    if (!this.intervalHandle) return;
+    clearInterval(this.intervalHandle);
+    this.intervalHandle = null;
+  }
+
+  getFrame(state) {
+    if (typeof this.updater == 'function') return this.updater(state);
+    if (typeof this.updater?.getFrame == 'function') {
+      this.updater.state = state;
+      return this.updater.getFrame();
+    }
+    throw new TypeError('Updater must be a function or implement getFrame()');
+  }
+
+  async writeFrame(state) {
+    if (this.first) {
+      this.prologue && (await this.writer.writeString(this.prologue));
+      this.first = false;
+    }
+
+    const frame = toStrings(this.getFrame(state));
+    if (!frame) return;
+
+    if (this.lastHeight) await this.writer.writeString('\r' + cursorUp(this.lastHeight));
+
+    this.lastHeight = frame.length;
+    if (this.noLastNewLine) --this.lastHeight;
+
+    await this.writer.write(frame, false, this.noLastNewLine);
+  }
+
+  async done() {
+    if (this.isDone) return;
+    this.isDone = true;
+    this.stopRefreshing();
+    this.epilogue && (await this.writer.writeString(this.epilogue));
+  }
+
+  async update(state = 'active') {
+    if (this.isDone || !this.writer.isTTY) return;
+    await this.writeFrame(state);
+  }
+
+  async final() {
+    if (this.isDone) return;
+    await this.writeFrame('finished');
+    await this.done();
+  }
+}
+
+export default Updater;