OrionUtils Module

🔧 PowerShell Utility Functions for File Management

A collection of PowerShell utility functions for file management and common administrative tasks.

Author: Sune Alexandersen Narud
Version: 1.6.0
Requires: PowerShell 5.1+, OrionDesign module (optional)
Gallery: https://www.powershellgallery.com/packages/OrionUtils
GitHub: https://github.com/suneworld/OrionUtils

---

📦 Installation

From the PowerShell Gallery (recommended):

Install-Module OrionUtils

From GitHub (manual):

# Clone the repo and import directly
Import-Module .\OrionUtils.psd1

Verify installation:

Get-Module OrionUtils
Get-Command -Module OrionUtils

📋 Dependencies

OrionUtils requires the OrionDesign module for visual output functions.

Import-Module OrionDesign
Import-Module OrionUtils

---

📁 Functions

Function	Description
Remove-StaleFile	Removes old files from a folder while keeping the newest N files
Test-FileLock	Tests if a file is locked by another process
Format-TimeSpan	Formats a TimeSpan to human-readable string
Get-TimeElapsed	Calculates and formats time elapsed since a date
Start-Stopwatch	Starts a named stopwatch for timing
Stop-Stopwatch	Stops stopwatch and records elapsed time
Get-Stopwatch	Gets running or completed stopwatch data
Reset-Stopwatch	Clears stopwatch data
Show-StopwatchSummary	Displays formatted performance summary
Wait-ForInput	Waits for key press, optionally with timer countdown
Write-Log	Structured logging to file
Export-MetricsToCSV	Export metrics to CSV with timestamps
Get-WindowsVersion	Converts OS version to friendly name

---

Remove-StaleFile

Removes old files from a folder while keeping the newest ones. Supports multiple filter patterns, grouping by name patterns, and automatically skips locked files.

Note: This function was previously named Remove-OldFiles-KeepNewest. Use Remove-StaleFile going forward.

Syntax

Remove-StaleFile [-Path] <String> [[-Keep] <Int32>] [-Filter] <String[]> 
                 [-NamePattern <String[]>] [-WhatIf] [-Confirm] [<CommonParameters>]

Parameters

Parameter	Type	Required	Default	Description
-Path	String	✅	—	The folder path to process
-Keep	Int	—	5	Number of newest files to keep
-Filter	String[]	✅	—	File filter pattern(s), e.g. *.log or @('*.xlsx', '*.csv')
-NamePattern	String[]	—	@()	Optional filename pattern(s) to group files by
-WhatIf	Switch	—	—	Shows what would happen without making changes
-Confirm	Switch	—	—	Prompts for confirmation before each deletion

Examples

Basic Usage - Keep 10 newest log files:

Remove-StaleFile -Path "C:\Logs" -Filter "*.log" -Keep 10

Preview what would be deleted (WhatIf):

Remove-StaleFile -Path "C:\Logs" -Filter "*.log" -Keep 5 -WhatIf

Multiple file types:

Remove-StaleFile -Path "C:\Output" -Filter @('*.xlsx', '*.csv') -Keep 10

Group by name pattern - keep newest for EACH pattern:

Remove-StaleFile -Path "C:\Reports" -Filter "*.csv" -NamePattern @(
    'DailyReport-*',
    'WeeklyReport-*'
) -Keep 7

This keeps the 7 newest DailyReport-*.csv AND the 7 newest WeeklyReport-*.csv files.

---

Test-FileLock

Tests if a file is currently locked by another process. By default, prompts the user to close the file and waits. Use -PassThru to return a boolean result instead.

Syntax

Test-FileLock [-FilePath] <String> [-PassThru] [-TimeoutSeconds <Int32>] [<CommonParameters>]

Parameters

Parameter	Type	Required	Default	Description
-FilePath	String	✅	—	The full path to the file to check
-PassThru	Switch	—	—	Returns $true if locked, $false if not (doesn't wait)
-TimeoutSeconds	Int	—	0	Maximum seconds to wait (0 = indefinite)

Examples

Wait for file to be available (interactive):

Test-FileLock -FilePath "C:\Data\Report.xlsx"
# If locked, prompts user to close the file

Check lock status without waiting:

if (Test-FileLock -FilePath "C:\Data\Report.xlsx" -PassThru) {
    Write-Warning "File is currently locked!"
} else {
    # Safe to process the file
}

Wait with timeout:

Test-FileLock -FilePath "C:\Data\Report.xlsx" -TimeoutSeconds 30

Ensure file is available before writing:

$reportPath = "C:\Output\Monthly-Report.xlsx"
Test-FileLock -FilePath $reportPath
$data | Export-Excel -Path $reportPath

Pipeline support:

"C:\File1.xlsx", "C:\File2.xlsx" | Test-FileLock -PassThru

---

🎨 Visual Output

OrionUtils integrates with OrionDesign for beautiful console output:

• Write-Action — Used for deletion confirmations
• Get-OrionTheme — Used for consistent color theming

---

📖 Getting Help

Use PowerShell's built-in help system:

# Full help with examples
Get-Help Remove-StaleFile -Full
Get-Help Test-FileLock -Full

# Just examples
Get-Help Remove-StaleFile -Examples

# Online help (if configured)
Get-Help Remove-StaleFile -Online

---

📝 Release Notes

v1.6.0 (February 2026)

• 🚧 Removed all legacy aliases; use canonical function names only
• 🔥 Removed legacy Wait-WithKeyInterrupt wrapper — use Wait-ForInput -Timer directly
• 🔧 Get-TimeElapsed continues to use Format-TimeSpan internally (reduces duplication)
• 🔧 Remove-FileWithLockCheck continues to use Test-FileLock -Silent

v1.5.0 (February 2026)

• 🔥 Removed legacy Wait-WithKeyInterrupt wrapper — use Wait-ForInput -Timer directly
• 🔧 Get-TimeElapsed continues to use Format-TimeSpan internally (reduces duplication)
• 🔧 Remove-FileWithLockCheck continues to use Test-FileLock -Silent

v1.4.0 (February 2026)

• ✨ Consolidated Wait-ForInput — Added -Timer parameter for timed waits with countdown
• 🔧 Get-TimeElapsed now uses Format-TimeSpan internally (reduced code duplication)
• 🔧 Remove-FileWithLockCheck now uses Test-FileLock -Silent (reduced code duplication)

v1.3.0 (February 2026)

• ✨ Added Stopwatch timing system (Start-Stopwatch, Stop-Stopwatch, Get-Stopwatch, Reset-Stopwatch, Show-StopwatchSummary)
• ✨ Added Write-Log for structured logging
• ✨ Added Export-MetricsToCSV for metrics export
• ✨ Added Format-TimeSpan and Get-TimeElapsed for time operations
• ✨ Added Get-WindowsVersion for OS version lookup

v1.1.0 (February 2026)

• ✨ Renamed Remove-OldFiles-KeepNewest → Remove-StaleFile (alias removed in v1.6.0)
• ✨ Added -WhatIf and -Confirm support to Remove-StaleFile
• ✨ Enhanced Test-FileLock with -PassThru and -TimeoutSeconds
• ✨ Added pipeline support to Test-FileLock
• 🔧 Moved internal helper to Private functions
• 📚 Complete Comment-Based Help documentation

v1.0.0 (Initial Release)

• Remove-OldFiles-KeepNewest function
• Test-FileLock function

---

📝 Version History

Version 1.0.0 (February 2026)

• Initial release
• Remove-OldFiles-KeepNewest - File cleanup with pattern matching
• Test-FileLock - File lock detection with user prompts

---

🤝 Related Modules

• OrionDesign - PowerShell UI Framework for beautiful terminal interfaces