From 11eae0d16eba092724a19bda95bd5d2b077b4644 Mon Sep 17 00:00:00 2001 From: kormic911 Date: Tue, 23 Sep 2025 21:21:59 -0500 Subject: [PATCH 1/2] Fixing a workflow issue, adding workflow to publish, fixing tasks, and updating some urls on the psd1 --- .devcontainer/devcontainer.json | 48 +++++++++---------- .github/workflows/publish.yaml | 34 +++++++++++++ .vscode/tasks.json | 12 ++--- .../PSFluentObjectValidation.psd1 | 6 +-- 4 files changed, 67 insertions(+), 33 deletions(-) create mode 100644 .github/workflows/publish.yaml diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index dcff9c4..041296a 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,27 +1,27 @@ { - "name": "PowerShell", - "dockerFile": "Dockerfile", - "customizations": { - "vscode": { - "settings": { - "terminal.integrated.profiles.linux": { - "bash": { - "path": "usr/bin/bash", - "icon": "terminal-bash" - }, - "zsh": { - "path": "usr/bin/zsh" - }, - "pwsh": { - "path": "/usr/bin/pwsh", - "icon": "terminal-powershell" - } - }, - "terminal.integrated.defaultProfile.linux": "pwsh" - }, - "extensions": ["ms-vscode.powershell", "davidanson.vscode-markdownlint"] - } - }, - "postCreateCommand": "pwsh -c './build.ps1 -Task Init -Bootstrap'" + "name": "PowerShell", + "dockerFile": "Dockerfile", + "customizations": { + "vscode": { + "settings": { + "terminal.integrated.profiles.linux": { + "bash": { + "path": "usr/bin/bash", + "icon": "terminal-bash" + }, + "zsh": { + "path": "usr/bin/zsh" + }, + "pwsh": { + "path": "/usr/bin/pwsh", + "icon": "terminal-powershell" + } + }, + "terminal.integrated.defaultProfile.linux": "pwsh" + }, + "extensions": ["ms-vscode.powershell", "davidanson.vscode-markdownlint"] + } + }, + "postCreateCommand": "pwsh -c './build.ps1 -Task Init -Bootstrap'" } diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml new file mode 100644 index 0000000..716e1fe --- /dev/null +++ b/.github/workflows/publish.yaml @@ -0,0 +1,34 @@ +name: Publish Module +on: + push: + branches: + - main + workflow_dispatch: +jobs: + build: + runs-on: windows-latest + steps: + # Get the current version + - uses: actions/checkout@v3 + - name: Install and cache PowerShell modules + id: psmodulecache + uses: potatoqualitee/psmodulecache@v6.2.1 + with: + modules-to-cache: BuildHelpers, Pester, psake, PowerShellBuild, PSScriptAnalyzer + - shell: pwsh + # Give an id to the step, so we can reference it later + id: check_if_versions_bumped + run: | + [version]$GalleryVersion = Get-NextNugetPackageVersion -Name PSFluentObjectValidation -ErrorAction Stop + [version]$GithubVersion = Get-MetaData -Path ./PSFluentObjectValidation/PSFluentObjectValidation.psd1 -PropertyName ModuleVersion -ErrorAction Stop + $bumped = $GithubVersion -ge $GalleryVersion + + # Set the output named "version_bumped" + Write-Host "::set-output name=version_bumped::$bumped" + + - name: Publish to PSGallery + shell: pwsh + if: steps.check_if_versions_bumped.outputs.version_bumped == 'True' + env: + PSGALLERY_API_KEY: ${{ secrets.PS_GALLERY_KEY }} + run: ./build.ps1 -Task Publish diff --git a/.vscode/tasks.json b/.vscode/tasks.json index f940e34..d318c20 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -33,12 +33,12 @@ { "label": "Clean", "type": "shell", - "command": "${cwd}/build.ps1 -Task Clean -Verbose" + "command": "cd '${cwd}' && ./build.ps1 -Task Clean -Verbose" }, { "label": "Test", "type": "shell", - "command": "${cwd}/build.ps1 -Task Test -Verbose", + "command": "cd '${cwd}' && ./build.ps1 -Task Test -Verbose", "group": { "kind": "test", "isDefault": true @@ -48,18 +48,18 @@ { "label": "Analyze", "type": "shell", - "command": "${cwd}/build.ps1 -Task Analyze -Verbose" + "command": "cd '${cwd}' && ./build.ps1 -Task Analyze -Verbose" }, { "label": "Pester", "type": "shell", - "command": "${cwd}/build.ps1 -Task Pester -Verbose", + "command": "cd '${cwd}' && ./build.ps1 -Task Pester -Verbose", "problemMatcher": "$pester" }, { "label": "Build", "type": "shell", - "command": "${cwd}/build.ps1 -Task Build -Verbose", + "command": "cd '${cwd}' && ./build.ps1 -Task Build -Verbose", "group": { "kind": "build", "isDefault": true @@ -68,7 +68,7 @@ { "label": "Publish", "type": "shell", - "command": "${cwd}/build.ps1 -Task Publish -Verbose" + "command": "cd '${cwd}' && ./build.ps1 -Task Publish -Verbose" } ] } diff --git a/PSFluentObjectValidation/PSFluentObjectValidation.psd1 b/PSFluentObjectValidation/PSFluentObjectValidation.psd1 index 67c01ec..f92c09d 100644 --- a/PSFluentObjectValidation/PSFluentObjectValidation.psd1 +++ b/PSFluentObjectValidation/PSFluentObjectValidation.psd1 @@ -5,7 +5,7 @@ Author = 'Joshua Wilson' CompanyName = 'PwshDevs' Copyright = '(c) 2025 PwshDevs. All rights reserved.' - Description = 'Contains a helper class and functions to validate object.' + Description = 'Contains a helper class and functions to validate objects.' PowerShellVersion = '5.1' FunctionsToExport = @('Test-Exists', 'Assert-Exists') CmdletsToExport = @() @@ -13,8 +13,8 @@ AliasesToExport = @('exists', 'asserts', 'tests') PrivateData = @{ PSData = @{ - Tags = @() - LicenseUri = '' + Tags = @('Validation', 'Object', 'Fluent', 'Helper', 'Assert', 'Test', 'Exists') + LicenseUri = 'https://github.com/pwshdevs/PSFluentObjectValidation/blob/main/LICENSE' ProjectUri = 'https://github.com/pwshdevs/PSFluentObjectValidation' ReleaseNotes = '' } From 34317c1ded67cc4078e0f07763edbc5af2bb6fb8 Mon Sep 17 00:00:00 2001 From: kormic911 Date: Tue, 23 Sep 2025 22:00:06 -0500 Subject: [PATCH 2/2] Updating readme --- README.md | 393 +++++++++++++----------------------------------------- 1 file changed, 95 insertions(+), 298 deletions(-) diff --git a/README.md b/README.md index bab4f0b..4386b44 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,32 @@ -# PSFluentObjectValidation: Complete Implementation Guide & Performance Analysis +# PSFluentObjectValidation: Complete Implementation Guide ## General Overview The PSFluentObjectValidation represents a comprehensive evolution from simple property validation to a high-performance, feature-rich validation engine with advanced array indexing capabilities. -**V3 (Foundational Excellence):** +## Installation -- **78.1% faster** than manual validation (13.06 μs vs 59.68 μs) -- **Optimized** for basic property validation scenarios -- **Production-ready** with comprehensive error handling - -**V4 (Revolutionary Features, Public release 1.0.0):** - -- **76.8% faster** than manual validation (13.86 μs vs 59.68 μs) -- **Advanced** array indexing and wildcard operations -- **Minimal Overhead**: Only 6.1% performance cost for massive feature expansionlity. - -### Key Achievements - -- **Performance Breakthrough**: 85.2% reduction in execution time compared to manual validation -- **Enhanced Syntax**: Revolutionary array indexing with `[0]`, `[1]`, and `[*]` wildcard support -- **C# Integration**: Leveraged C# for massive performance gains -- **Backward Compatibility**: Maintains simple syntax while adding powerful new features - -## Performance Results Overview - -### Ultimate Performance Comparison - -Based on 10,000 iterations with corrected V3-compatible scenario testing: - -| Version | Average Performance | vs Manual | Technology | Array Support | -|---------|-------------------|-----------|------------|---------------| -| **Manual Validation** | 59.68 μs | ±0% | Native PowerShell | Limited | -| **V1 (PowerShell)** | 352.48 μs | +491% | Pure PowerShell | ❌ | -| **V2 (PowerShell)** | 318.71 μs | +434% | Pure PowerShell | ❌ | -| **V3 (C# Basic)** | **13.06 μs** | **-78.1%** | C# Compiled | ❌ | -| **V4 (C# Enhanced)** | **13.86 μs** | **-76.8%** | C# + Array Logic | ✅ | - -### Performance Highlights - -- **V3**: **78.1% faster** than manual validation - C# performance breakthrough -- **V4**: **76.8% faster** than manual validation with revolutionary array features -- **V4 vs V3**: Only **6.1% slower** - excellent trade-off for massive feature expansion -- **Both C# versions**: **27x faster** than V1, **23x faster** than V2 - -## Features & Capabilities Matrix - -| Feature | V1 | V2 | V3 | V4 | Description | -|---------|----|----|----|----|-------------| -| **Basic Properties** | ✅ | ✅ | ✅ | ✅ | `user.name`, `config.host` | -| **Validation Suffixes** | ✅ | ✅ | ✅ | ✅ | `property!` (non-empty), `property?` (exists) | -| **Nested Navigation** | ✅ | ✅ | ✅ | ✅ | `user.profile.settings.theme` | -| **Array Indexing** | ❌ | ❌ | ❌ | ✅ | `users[0].name`, `products[1].title` | -| **Wildcard Arrays** | ❌ | ❌ | ❌ | ✅ | `users[*].name` (all elements) | -| **Array + Validation** | ❌ | ❌ | ❌ | ✅ | `users[*].email!` (all non-empty) | -| **Deep Array Access** | ❌ | ❌ | ❌ | ✅ | `products[0].category.name` | -| **Error Handling** | Basic | Basic | Enhanced | Advanced | Bounds checking, null safety | +```powershell +Install-PSResource -Name PSFluentObjectValidation +# or +Install-Module -Name PSFluentObjectValidation + +# Verify installation (long style) +Test-Exists -in @{ test = "value" } -with "test!" +# (short hand) +exists -with "test!" -in @{ test = "value" } +# or alternative +tests -with "test!" -in @{ test = "value" } +# or if you'd rather have thrown errors +Assert-Exists -in @{ test = "value" } -with "test!" +# or you can use a short hand version +asserts -with "test!" -in @{ test = "value" } +# Should return: True +``` ## Syntax Guide -### V4 Enhanced Syntax Reference - -#### Basic Property Access +### Basic Property Access ```powershell exists -with "user.name" -in $data # Simple property @@ -69,181 +34,50 @@ exists -with "user.profile.age" -in $data # Nested objects exists -with "config.db.host" -in $data # Deep nesting ``` -#### Validation Suffixes - +As an example, you would normally test this like so ```powershell -Test-Exists $data "user.email!" # Non-empty validation -Test-Exists $data "user.profile?" # Object existence -Test-Exists $data "settings.theme!" # Non-empty string +if(-not $data.user -or -not $data.user.name -or -not $data.user.profile -or -not $data.user.profile.age) { + # do something when any of these fields do not exist +} +# vs. PSFluentObjectValidation +if(-not (exists -with "user.name" -in $data) -or -not (exists -with "user.profile.age" -in $data)) { + # do something when any of these fields do not exist +} ``` -#### Array Indexing (V4 Exclusive) - -```powershell -Test-Exists $data "users[0].name" # First element -Test-Exists $data "users[1].email" # Second element -Test-Exists $data "products[2].title" # Third element -``` -#### Wildcard Array Validation (V4 Exclusive) +### Validation Suffixes ```powershell -Test-Exists $data "users[*].name" # All users have names -Test-Exists $data "users[*].email!" # All users have non-empty emails -Test-Exists $data "products[*].active" # All products have active property +exists -with "user.email!" -in $data # Non-empty validation +exists -with "user.profile?" -in $data # Object existence +exists -with "settings.theme!" -in $data # Non-empty string ``` -#### Advanced Combinations (V4 Exclusive) +### Array Indexing ```powershell -Test-Exists $data "users[0].profile.settings.theme!" # Deep + validation -Test-Exists $data "products[*].category.name!" # Wildcard + deep + validation -Test-Exists $data "orders[1].items[*].price" # Nested array access +exists -with "users[0].name" -in $data # First element +exists -with "users[1].email" -in $data # Second element +exists -with "products[2].title" -in $data # Third element ``` -## Technical Implementation Details - -### Architecture Evolution - -#### V1: Pure PowerShell Foundation - -- **Technology**: Native PowerShell functions -- **Syntax**: `property{}` for objects, `property[]` for arrays -- **Performance**: 513.93 μs average (baseline) -- **Limitations**: No array indexing, high overhead +### Wildcard Array Validation -#### V2: Unified Syntax - -- **Technology**: Improved PowerShell with unified syntax -- **Syntax**: `property?` for both objects and arrays -- **Performance**: 485.87 μs average (5% improvement over V1) -- **Benefits**: Cleaner syntax, slightly better performance - -#### V3: C# Performance Breakthrough - -- **Technology**: Compiled C# with PowerShell wrapper -- **Performance**: Dramatic improvement (exact metrics limited by test scope) -- **Benefits**: Near-native performance, maintained PowerShell interface -- **Foundation**: Set stage for V4 enhancements - -#### V4: Enhanced C# with Array Mastery (Public Release v1.0.0) - -- **Technology**: Advanced C# with comprehensive array handling -- **Performance**: 15.1 μs average (**85.2% improvement**) -- **Features**: Full array indexing, wildcard validation, advanced error handling -- **Innovation**: Unique array validation beyond standard C# capabilities - -### V4 Core Components - -#### PSFluentObjectValidation Class - -```csharp -public static class PSFluentObjectValidation -{ - // Regex patterns for syntax parsing - private static readonly Regex PropertyWithValidation = new Regex(@"^(.+)([?!])$"); - private static readonly Regex ArrayIndexPattern = new Regex(@"^(.+)\[(\*|\d+)\]$"); - - // Main validation methods - public static bool TestExists(object inputObject, string key) - public static void AssertExists(object inputObject, string key) -} +```powershell +exists -with "users[*].name" -in $data # All users have names +exists -with "users[*].email!" -in $data # All users have non-empty emails +exists -with "products[*].active" -in $data # All products have active property ``` -#### WildcardArrayWrapper Class +### Advanced Combinations -```csharp -public class WildcardArrayWrapper -{ - public object ArrayObject { get; } - // Enables wildcard [*] validation across all array elements -} +```powershell +exists -with "users[0].profile.settings.theme!" -in $data # Deep + validation +exists -with "products[*].category.name!" -in $data # Wildcard + deep + validation +exists -with "orders[1].items[*].price" -in $data # Nested array access ``` -#### Key Processing Methods - -- **ProcessKeyPart**: Main routing logic for syntax parsing -- **ProcessArrayAccess**: Handles `[index]` and `[*]` syntax -- **ProcessWildcardPropertyAccess**: Validates properties across all array elements -- **ProcessPropertyWithValidation**: Manages `!` and `?` suffix validation - -## Detailed Performance Analysis - -### Corrected Test Results & V3 Performance - -#### V3-Compatible Scenarios (Basic Property Validation) - -**All versions tested on scenarios they support - -| Scenario | Manual | V1 | V2 | **V3** | **V4** | V3 vs Manual | V4 vs V3 | -|----------|--------|----|----|--------|--------|--------------|----------| -| **Basic Property** | 56.6 μs | 229.09 μs | 242.1 μs | **15.4 μs** | **14.46 μs** | **-72.8%** | -6.1% | -| **Nested Property** | 71.73 μs | 315.86 μs | 295.3 μs | **10.93 μs** | **11.43 μs** | **-84.8%** | +4.6% | -| **Deep Nesting** | 54.66 μs | 355.66 μs | 360.12 μs | **11.75 μs** | **12.6 μs** | **-78.5%** | +7.2% | -| **Non-empty Validation** | 56.95 μs | 243.18 μs | 294.02 μs | **13.84 μs** | **14.14 μs** | **-75.7%** | +2.2% | -| **Object Validation** | 63.12 μs | 617.1 μs | 318.05 μs | **11.14 μs** | **11.78 μs** | **-82.4%** | +5.7% | -| **Deep Validation** | 55.04 μs | 354.01 μs | 402.67 μs | **15.27 μs** | **18.75 μs** | **-72.3%** | +22.8% | - -#### V4-Only Scenarios (Enhanced Array Features) - -**These scenarios only work in V4 due to array indexing and wildcard features - -| Scenario | Manual | V1 | V2 | V3 | **V4** | V4 Improvement | -|----------|--------|----|----|----|----|----------------| -| **Array Index [0]** | 72.64 μs | 543.86 μs | 549.22 μs | N/A | **12.0 μs** | **-83.5%** | -| **Array Index [1]** | 55.55 μs | 605.87 μs | 555.24 μs | N/A | **12.05 μs** | **-78.3%** | -| **Array Index [2]** | 56.15 μs | 553.48 μs | 554.88 μs | N/A | **12.72 μs** | **-77.3%** | -| **Array + Validation** | 59.05 μs | 596.04 μs | 569.61 μs | N/A | **12.35 μs** | **-79.1%** | -| **Deep Array Access** | 59.14 μs | 553.99 μs | 620.44 μs | N/A | **13.15 μs** | **-77.8%** | -| **Deep Array + Validation** | 59.05 μs | 556.65 μs | 545.56 μs | N/A | **13.25 μs** | **-77.6%** | -| **Wildcard Basic** | 153.11 μs | 637.44 μs | 562.49 μs | N/A | **12.38 μs** | **-91.9%** | -| **Wildcard + Validation** | 159.02 μs | 556.2 μs | 576.06 μs | N/A | **13.51 μs** | **-91.5%** | -| **Wildcard Deep** | 153.1 μs | 570.35 μs | 547.16 μs | N/A | **13.03 μs** | **-91.5%** | -| **Wildcard Deep + Validation** | 182.76 μs | 607.53 μs | 558.32 μs | N/A | **13.48 μs** | **-92.6%** | - -### Performance Insights - -#### The V3 vs V4 Trade-off Analysis - -**V3 Achievements:** - -- **78.1% faster** than manual validation -- **Exceptional** basic property validation performance -- **Lightweight** C# implementation without array overhead - -**V4 Achievements:** - -- **76.8% faster** than manual validation -- **Revolutionary** array indexing and wildcard capabilities -- Only **6.1% slower** than V3 while adding massive functionality - -#### Why Both V3 and V4 are Revolutionary - -1. **C# Execution**: Eliminates PowerShell interpretation overhead -2. **Optimized Regex Patterns**: Pre-compiled regex for syntax parsing -3. **Efficient Memory Management**: Minimal object allocations -4. **Smart Caching**: Type reflection results cached for repeated access -5. **Advanced Algorithm Design**: Optimized validation logic flow - -#### Performance Categories - -**V3 Performance (Basic Features):** - -- **Exceptional**: 82-85% improvement (object validation, nested properties) -- **Outstanding**: 75-78% improvement (basic properties, deep nesting) -- **Solid**: 72-73% improvement (validation features) - -**V4 Performance (Enhanced Features):** - -- **Exceptional**: 91-93% improvement (wildcard operations) -- **Outstanding**: 77-83% improvement (array indexing) -- **Solid**: 76-78% improvement (basic properties with array overhead) - -**V4 vs V3 Trade-off:** - -- **Worth It**: Only 6.1% average performance cost for revolutionary array features -- **Best Choice**: V4 for new projects, V3 for pure performance on basic scenarios - ## Usage Examples ### Real-World Scenarios @@ -263,13 +97,13 @@ $apiResponse = @{ } # Validate all users have required fields -Test-Exists $apiResponse "users[*].id" # All users have IDs -Test-Exists $apiResponse "users[*].name!" # All users have non-empty names -Test-Exists $apiResponse "users[*].email!" # All users have non-empty emails +exists -in $apiResponse -with "users[*].id" # All users have IDs +exists -in $apiResponse -with "users[*].name!" # All users have non-empty names +exists -in $apiResponse -with "users[*].email!" # All users have non-empty emails # Validate specific user data -Test-Exists $apiResponse "users[0].active" # First user has active status -Test-Exists $apiResponse "metadata.total!" # Metadata has non-empty total +exists -in $apiResponse -with "users[0].active" # First user has active status +exists -in $apiResponse -with "metadata.total!" # Metadata has non-empty total ``` #### Configuration Validation @@ -291,10 +125,10 @@ $config = @{ } # Validate critical configuration -Test-Exists $config "database.host!" # Non-empty host -Test-Exists $config "database.credentials.password!" # Non-empty password -Test-Exists $config "servers[*].name!" # All servers have names -Test-Exists $config "servers[*].ip!" # All servers have IPs +exists -in $config -with "database.host!" # Non-empty host +exists -in $config -with "database.credentials.password!" # Non-empty password +exists -in $config -with "servers[*].name!" # All servers have names +exists -in $config -with "servers[*].ip!" # All servers have IPs ``` #### E-commerce Data Validation @@ -313,30 +147,30 @@ $order = @{ } # Comprehensive order validation -Test-Exists $order "id!" # Order has ID -Test-Exists $order "customer.email!" # Customer has email -Test-Exists $order "items[*].sku!" # All items have SKUs -Test-Exists $order "items[*].price" # All items have prices -Test-Exists $order "items[0].quantity" # First item has quantity +exists -in $order -with "id!" # Order has ID +exists -in $order -with "customer.email!" # Customer has email +exists -in $order -with "items[*].sku!" # All items have SKUs +exists -in $order -with "items[*].price" # All items have prices +exists -in $order -with "items[0].quantity" # First item has quantity ``` ## Error Handling & Edge Cases -### V4 Advanced Error Handling +### Advanced Error Handling #### Comprehensive Error Messages ```powershell # Array bounds checking -Test-Exists $data "users[10].name" # Returns false for out-of-bounds -Assert-Exists $data "users[10].name" # Throws: "Array index [10] is out of bounds" +tests -in $data -with "users[10].name" # Returns false for out-of-bounds +asserts -in $data -with "users[10].name" # Throws: "Array index [10] is out of bounds" # Null safety -Test-Exists $data "user.profile.settings" # Handles null intermediate objects -Assert-Exists $data "missing.property" # Throws: "Property 'missing' does not exist" +tests -in $data -with "user.profile.settings" # Handles null intermediate objects +asserts -in $data -with "missing.property" # Throws: "Property 'missing' does not exist" # Type validation -Test-Exists $data "config.port[0]" # Throws: "Property 'port' is not an array" +tests -in $data -with "config.port[0]" # Throws: "Property 'port' is not an array" ``` #### Wildcard Validation Error Handling @@ -350,52 +184,16 @@ Test-Exists $data "users[*].email!" # Validates ALL users have no Assert-Exists $data "users[*].phone!" # Throws if ANY user lacks phone ``` -## Project Impact & Outcomes - -### Development Journey - -1. **Phase 1**: Basic PowerShell implementation with functional syntax -2. **Phase 2**: Syntax refinement and performance optimization -3. **Phase 3**: C# integration for performance breakthrough -4. **Phase 4**: Enhanced array indexing and wildcard validation - -### Technical Achievements - -- **Performance Revolution**: 85.2% improvement over manual validation -- **Feature Innovation**: Industry-leading array validation syntax -- **Backwards Compatibility**: Seamless upgrade path from V1-V3 -- **Production Ready**: Comprehensive error handling and edge case coverage - -### Business Value - -- **Developer Productivity**: Dramatically simplified complex validation logic -- **Code Reliability**: Robust validation reduces production errors -- **Performance Optimization**: Minimal overhead for critical path operations -- **Maintainability**: Clean, readable validation syntax - -## Technical Reference - -### Installation & Setup - -```powershell -# Load the V4 enhanced asserter -. "path\to\asserter-v4-enhanced-arrays.ps1" - -# Verify installation -Test-Exists @{ test = "value" } "test!" -# Should return: True -``` - ### Function Reference -#### `Test-Exists` +#### `Test-Exists` or `tests` or `exists` **Purpose**: Safely test property existence and validation **Syntax**: `Test-Exists $object $propertyPath` **Returns**: `$true` if validation passes, `$false` otherwise **Error Handling**: Never throws exceptions -#### `Assert-Exists` +#### `Assert-Exists` or `asserts` **Purpose**: Assert property existence with detailed error reporting **Syntax**: `Assert-Exists $object $propertyPath` @@ -431,39 +229,38 @@ Test-Exists @{ test = "value" } "test!" - **Parallel Validation**: Multi-threaded wildcard processing - **Memory Optimization**: Zero-allocation validation paths -## Conclusion - -The PowerShell Asserter Suite represents a **revolutionary advancement** in PowerShell validation technology. Through strategic evolution from V1 to V4, we've achieved unprecedented performance gains while maintaining simplicity. - -### Performance Achievements - -**V3 (Foundational Excellence):** - -- **78.1% faster** than manual validation (13.06 μs vs 59.68 μs) -- **Optimized** for basic property validation scenarios -- **Production-ready** with comprehensive error handling +## Performance Results Overview -**V4 (Revolutionary Features):** +### Performance Comparison -- **76.8% faster** than manual validation (13.86 μs vs 59.68 μs) -- **Advanced** array indexing and wildcard operations -- **Minimal Overhead**: Only 6.1% performance cost for massive feature expansion +Originally this module was written in pure powershell but comparing it against just standard manual testing showed it was very slow (in micro seconds, still fairly quick overall). The the module was rewritten to use a different format for testing, which improved performance but it was still relatively slow compared to just manual validation. The module was then implemented in C# and saw significate performance improvements over even manual processing. The module was updated a 4th time to handle arrays as there are times when its better to test before looping with | ForEach-Object. Below is a series of tests written against all 5 methods. -### Strategic Technology Choices +Based on 10,000 iterations with corrected V3-compatible scenario testing: -- **Performance**: Both V3 and V4 exceed all targets with revolutionary speed improvements -- **Functionality**: V4 delivers unique array validation capabilities not available elsewhere -- **Usability**: Maintained simple, intuitive syntax throughout evolution -- **Reliability**: Comprehensive testing across 16 complex scenarios +| Version | Average Performance | vs Manual | Technology | Array Support | +|---------|-------------------|-----------|------------|---------------| +| **Manual Validation** | 59.68 μs | ±0% | Native PowerShell | Limited | +| **V1 (PowerShell)** | 352.48 μs | +491% | Pure PowerShell | ❌ | +| **V2 (PowerShell)** | 318.71 μs | +434% | Pure PowerShell | ❌ | +| **V3 (C# Basic)** | **13.06 μs** | **-78.1%** | C# Compiled | ❌ | +| **V4 (C# Current)** | **13.86 μs** | **-76.8%** | C# + Array Logic | ✅ | -### Version Recommendations +### Performance Highlights -- **Choose V3** for pure performance on basic property validation -- **Choose V4** for new projects requiring array features - minimal performance trade-off -- **Both versions** deliver exceptional 75%+ performance improvements over manual validation +- **V3**: **78.1% faster** than manual validation - C# performance breakthrough +- **V4**: **76.8% faster** than manual validation with revolutionary array features +- **V4 vs V3**: Only **6.1% slower** - excellent trade-off for massive feature expansion +- **Both C# versions**: **27x faster** than V1, **23x faster** than V2 -The journey from basic property validation to advanced array indexing demonstrates the power of iterative improvement and strategic technology choices. This suite sets a new standard for PowerShell validation tools and provides a solid foundation for future enhancements. +## Features & Capabilities Matrix -*Generated from comprehensive performance testing on September 23, 2025* -*Test Environment: Windows PowerShell, 10,000 iterations, 16 test scenarios* -*Repository: PowerShell Asserter Suite V3/V4 Comprehensive Analysis* +| Feature | V1 | V2 | V3 | V4 | Description | +|---------|----|----|----|----|-------------| +| **Basic Properties** | ✅ | ✅ | ✅ | ✅ | `user.name`, `config.host` | +| **Validation Suffixes** | ✅ | ✅ | ✅ | ✅ | `property!` (non-empty), `property?` (exists) | +| **Nested Navigation** | ✅ | ✅ | ✅ | ✅ | `user.profile.settings.theme` | +| **Array Indexing** | ❌ | ❌ | ❌ | ✅ | `users[0].name`, `products[1].title` | +| **Wildcard Arrays** | ❌ | ❌ | ❌ | ✅ | `users[*].name` (all elements) | +| **Array + Validation** | ❌ | ❌ | ❌ | ✅ | `users[*].email!` (all non-empty) | +| **Deep Array Access** | ❌ | ❌ | ❌ | ✅ | `products[0].category.name` | +| **Error Handling** | Basic | Basic | Enhanced | Advanced | Bounds checking, null safety |