@socketsecurity/lib/dist/stdio/stderr.d.ts

Core utilities and infrastructure for Socket.dev security tools

/**
 * @fileoverview Standard error stream utilities.
 * Provides utilities for writing to stderr with formatting and control.
 */
// Get the actual stderr stream
declare const stderr: NodeJS.WriteStream;
/**
 * Write a line to stderr with trailing newline.
 * Used for error messages, warnings, and diagnostic output.
 *
 * @param text - Text to write
 * @default text ''
 *
 * @example
 * ```ts
 * writeErrorLine('Error: File not found')
 * writeErrorLine() // Write empty line
 * ```
 */
export declare function writeErrorLine(text?: string): void;
/**
 * Write text to stderr without adding a newline.
 *
 * @param text - Text to write
 *
 * @example
 * ```ts
 * writeError('Downloading...')
 * // Later update progress
 * ```
 */
export declare function writeError(text: string): void;
/**
 * Clear the current line on stderr.
 * Only works in TTY environments.
 *
 * @example
 * ```ts
 * writeError('Processing...')
 * clearLine()
 * writeError('Done!')
 * ```
 */
export declare function clearLine(): void;
/**
 * Move cursor to specific position on stderr.
 * Only works in TTY environments.
 *
 * @param x - Column position (0-based)
 * @param y - Row position (0-based, optional)
 *
 * @example
 * ```ts
 * cursorTo(0) // Move to start of line
 * cursorTo(10, 5) // Move to column 10, row 5
 * ```
 */
export declare function cursorTo(x: number, y?: number | undefined): void;
/**
 * Check if stderr is connected to a TTY (terminal).
 *
 * @returns `true` if stderr is a TTY, `false` if piped/redirected
 *
 * @example
 * ```ts
 * if (isTTY()) {
 *   // Show colored error messages
 * } else {
 *   // Use plain text
 * }
 * ```
 */
export declare function isTTY(): boolean;
/**
 * Get the number of columns (width) in the terminal.
 *
 * @returns Terminal width in characters
 * @default 80
 *
 * @example
 * ```ts
 * const width = getColumns()
 * console.error(`Terminal is ${width} characters wide`)
 * ```
 */
export declare function getColumns(): number;
/**
 * Get the number of rows (height) in the terminal.
 *
 * @returns Terminal height in lines
 * @default 24
 *
 * @example
 * ```ts
 * const height = getRows()
 * console.error(`Terminal is ${height} lines tall`)
 * ```
 */
export declare function getRows(): number;
/**
 * Write a formatted warning message to stderr.
 *
 * @param message - Warning message text
 * @param prefix - Prefix label for the warning
 * @default prefix 'Warning'
 *
 * @example
 * ```ts
 * writeWarning('Deprecated API usage')
 * // Output: 'Warning: Deprecated API usage'
 *
 * writeWarning('Invalid config', 'Config')
 * // Output: 'Config: Invalid config'
 * ```
 */
export declare function writeWarning(message: string, prefix?: string): void;
/**
 * Write a formatted error message to stderr.
 *
 * @param message - Error message text
 * @param prefix - Prefix label for the error
 * @default prefix 'Error'
 *
 * @example
 * ```ts
 * writeErrorFormatted('File not found')
 * // Output: 'Error: File not found'
 *
 * writeErrorFormatted('Connection failed', 'Network')
 * // Output: 'Network: Connection failed'
 * ```
 */
export declare function writeErrorFormatted(message: string, prefix?: string): void;
/**
 * Write an error's stack trace to stderr.
 * Falls back to formatted error message if no stack is available.
 *
 * @param error - Error object to write
 *
 * @example
 * ```ts
 * try {
 *   throw new Error('Something went wrong')
 * } catch (err) {
 *   writeStackTrace(err as Error)
 * }
 * ```
 */
export declare function writeStackTrace(error: Error): void;
// Export the raw stream for advanced usage
export { stderr };