stdio.ts

/**
 * @fileoverview Stdio configuration helpers for `spawn` callers.
 *
 * `isStdioType` is dual-purpose:
 *   - One arg: validate that a value is a known stdio mode
 *     (`'pipe'` / `'ignore'` / `'inherit'` / `'overlapped'`).
 *   - Two args: check whether the caller's stdio config matches a
 *     specific mode. Useful in spinner-pause logic — the spinner only
 *     stops when the child writes to a non-piped stream that would
 *     otherwise interleave with spinner redraws.
 *
 * Two-arg behavior special-cases `null` / `undefined` ↔ `'pipe'`
 * because Node.js defaults unspecified entries to `'pipe'`. The
 * three-element-array branch handles the common `[in, out, err]`
 * tuple where all three streams use the same mode.
 */

import { isArray } from '../arrays/predicates'

import type { StdioType } from './types'

/**
 * Check if stdio configuration matches a specific type.
 * When called with one argument, validates if it's a valid stdio type.
 * When called with two arguments, checks if the stdio config matches the specified type.
 *
 * @param {string | string[]} stdio - Stdio configuration to check
 * @param {StdioType | undefined} type - Expected stdio type (optional)
 * @returns {boolean} `true` if stdio matches the type or is valid
 *
 * @example
 * // Check if valid stdio type
 * isStdioType('pipe') // true
 * isStdioType('invalid') // false
 *
 * @example
 * // Check if stdio matches specific type
 * isStdioType('pipe', 'pipe') // true
 * isStdioType(['pipe', 'pipe', 'pipe'], 'pipe') // true
 * isStdioType('ignore', 'pipe') // false
 */
/*@__NO_SIDE_EFFECTS__*/
export function isStdioType(
  stdio: string | string[],
  type?: StdioType | undefined,
): boolean {
  // If called with one argument, check if it's a valid stdio type.
  // biome-ignore lint/complexity/noArguments: Function overload detection for single vs two-arg calls.
  if (arguments.length === 1) {
    const validTypes = ['pipe', 'ignore', 'inherit', 'overlapped']
    return typeof stdio === 'string' && validTypes.includes(stdio)
  }
  // Original two-argument behavior.
  // Accept null/undefined as equivalent to 'pipe' because Node.js defaults
  // unspecified stdio entries to 'pipe'. Tests explicitly cover this contract.
  return (
    stdio === type ||
    ((stdio === null || stdio === undefined) && type === 'pipe') ||
    (isArray(stdio) &&
      stdio.length > 2 &&
      stdio[0] === type &&
      stdio[1] === type &&
      stdio[2] === type)
  )
}