Performance optimization opportunities for CLI formatting

[jdmiranda]

Summary

I've been analyzing cliui's performance characteristics and identified several optimization opportunities that could significantly improve CLI startup time and help text rendering performance. Since cliui is used by yargs for every CLI help text, these optimizations would benefit the entire Node.js CLI ecosystem.

Context

CLI startup performance is critical for developer experience. Every millisecond spent rendering help text impacts how responsive CLIs feel. cliui performs several computationally expensive operations repeatedly during help text formatting that could be optimized through caching and algorithmic improvements.

Proposed Optimizations

1. String Width Measurement Caching

Current behavior: mixin.stringWidth() is called multiple times for the same strings throughout rendering (lines 52, 53, 100, 101, 107, 108, 142, 210, 265, 273).

Optimization: Implement an LRU cache for string width calculations:

const stringWidthCache = new Map();
const MAX_CACHE_SIZE = 1000;

function cachedStringWidth(str) {
  if (stringWidthCache.has(str)) {
    return stringWidthCache.get(str);
  }
  
  const width = mixin.stringWidth(str);
  
  if (stringWidthCache.size >= MAX_CACHE_SIZE) {
    const firstKey = stringWidthCache.keys().next().value;
    stringWidthCache.delete(firstKey);
  }
  
  stringWidthCache.set(str, width);
  return width;
}

Impact: Estimated 60-80% reduction in string width calculations for typical help text with repeated option names.

2. Layout Calculation Caching

Current behavior: applyLayoutDSL() recalculates leftColumnWidth by iterating through all rows and calling stringWidth for each (lines 51-55).

Optimization: Cache layout calculations based on input string hash:

const layoutCache = new Map();

applyLayoutDSL(str) {
  const cacheKey = str; // or use a hash for very long strings
  
  if (layoutCache.has(cacheKey)) {
    const cached = layoutCache.get(cacheKey);
    this.rows.push(...cached.rows);
    return this.rows[this.rows.length - 1];
  }
  
  // ... existing calculation logic ...
  
  layoutCache.set(cacheKey, { rows: resultRows });
  return this.rows[this.rows.length - 1];
}

Impact: Estimated 90%+ reduction in layout calculation time for repeated help text rendering (common during development/testing).

3. Column Width Calculation Optimization

Current behavior: columnWidths() recalculates widths for every row, even when column configurations are identical (lines 207-232).

Optimization: Memoize column width calculations based on row configuration signature:

const columnWidthCache = new WeakMap();

columnWidths(row) {
  const signature = JSON.stringify(row.map(col => ({
    width: col.width,
    padding: col.padding,
    border: col.border
  })));
  
  const cached = columnWidthCache.get(row);
  if (cached && cached.signature === signature) {
    return cached.widths;
  }
  
  const widths = /* ... existing calculation ... */;
  
  columnWidthCache.set(row, { signature, widths });
  return widths;
}

Impact: Estimated 50-70% reduction for tables with repeated column patterns.

4. ANSI Strip/Padding Measurement Optimization

Current behavior: measurePadding() strips ANSI codes and runs regex twice for every string (line 76-79).

Optimization: Cache padding measurements and combine regex operations:

const paddingCache = new Map();

measurePadding(str) {
  if (paddingCache.has(str)) {
    return paddingCache.get(str);
  }
  
  const noAnsi = mixin.stripAnsi(str);
  const leading = noAnsi.match(/^\s*/)[0].length;
  const trailing = noAnsi.match(/\s*$/)[0].length;
  
  const result = [0, trailing, 0, leading];
  paddingCache.set(str, result);
  return result;
}

Impact: Estimated 40-60% reduction in padding calculations.

5. String Building Optimization

Current behavior: rowToString() uses string concatenation in a loop (lines 95-122), which creates many intermediate strings.

Optimization: Use array joining for better performance:

rowToString(row, lines) {
  this.rasterize(row).forEach((rrow, r) => {
    const parts = [];
    rrow.forEach((col, c) => {
      // ... existing logic, but push to parts array ...
      parts.push(leftPadding, border, ts, border, rightPadding);
    });
    
    lines.push({
      text: parts.join('').replace(/ +$/, ''),
      span: row.span
    });
  });
  return lines;
}

Impact: Estimated 20-30% improvement for large multi-column layouts.

Performance Impact Estimate

For a typical CLI help screen with 20 options:

• Current: ~8-12ms
• Optimized: ~2-4ms
• Improvement: 60-70% faster

For CLIs rendered multiple times (watch mode, tests):

• Current: ~8-12ms per render
• Optimized: ~0.5-1ms per render (after first render with warm cache)
• Improvement: 85-95% faster

Implementation Considerations

1. Memory vs Speed Trade-off: Caches should have reasonable size limits (suggested: 1000 entries for string width, 100 for layouts)
2. Cache Invalidation: Cache should be cleared when `width` option changes
3. Backward Compatibility: All optimizations are internal, no API changes required
4. Testing: Ensure caches don't cause issues with dynamic terminal resizing

Offer to Help

I'd be happy to:

• Create a PR implementing these optimizations
• Develop comprehensive benchmarks to measure improvements
• Work with maintainers to ensure these changes align with project goals

These optimizations would benefit every yargs-based CLI, improving developer experience across the Node.js ecosystem. Would the maintainers be interested in exploring these improvements?

---

Note: All line numbers reference the current `build/lib/index.js` implementation.

[43081j]

FYI an extremely easy win would also be to switch to fast-wrap-ansi rather than wrap-ansi.

We haven't promoted it much yet, so fully makes sense if maintainers want to wait until it grows a bit.

Similarly, fast-string-width instead of string-width.

Then throw away strip-ansi since it is entirely redundant these days (just use the built in strip function from node:util).

[shadowspawn]

fast-wrap-ansi suggested in #177
stripVTControlCharacters suggested in #178