Add type-safe query string utilities and samples

Introduces QueryStringBuilder, RouterStateExtensions, and RouterNavigationExtensions for fluent, type-safe query string manipulation and parsing. Updates documentation and sample components to demonstrate new query string features, including typed parameter parsing, advanced navigation, and comprehensive usage examples.

Author: Taiizor

.gitignore

@@ -167,6 +167,7 @@ ClientBin/
 *.pfx
 *.publishsettings
 node_modules/
+bun.lock
 
 # RIA/Silverlight projects
 Generated_Code/

CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.11] - 2025-11-24
+
+### Added
+- **Query String Helpers and Utilities**: Comprehensive type-safe query string manipulation
+  - `QueryStringBuilder` class with fluent API for building query strings
+  - 15 type-safe `Add()` method overloads supporting string, int, long, decimal, double, bool, DateTime, Guid, enum, and nullable variants
+  - 15 type-safe `Set()` method overloads for replacing values (prevents duplicates)
+  - `RouterStateExtensions` with typed query parameter parsing methods: `GetQueryInt()`, `GetQueryBool()`, `GetQueryDateTime()`, etc.
+  - `GetAllQueryParams()` method to retrieve all query parameters as a dictionary
+  - `RouterNavigationExtensions` for enhanced navigation with query strings
+  - `NavigateToWithQuery()` for fluent query string building during navigation
+  - `NavigateToWithUpdatedQuery()` for updating specific parameters while preserving others
+  - `NavigateToWithRemovedQuery()` and `NavigateToWithClearedQuery()` for parameter removal
+  - `NavigateToWithSingleQuery()` convenience methods for single parameter navigation
+  - Automatic URL encoding via `Uri.EscapeDataString`
+  - Safe parsing with `TryParse` and default value support
+  - Comprehensive XML documentation with usage examples
+
+### Changed
+- Updated README.md with Query String Utilities documentation and usage examples
+- Enhanced UserList sample component to display all query parameters using `GetAllQueryParams()`
+- Updated project structure documentation to reflect new Utilities directory
+
 ## [1.0.10] - 2025-11-19
 
 ### Added
@@ -151,6 +174,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - FEATURES.md detailing all capabilities
 - Sample application demonstrating key features
 
+[1.0.11]: https://github.com/Taiizor/Blazouter/compare/v1.0.10...v1.0.11
 [1.0.10]: https://github.com/Taiizor/Blazouter/compare/v1.0.9...v1.0.10
 [1.0.9]: https://github.com/Taiizor/Blazouter/compare/v1.0.5...v1.0.9
 [1.0.6-1.0.8]: https://github.com/Taiizor/Blazouter/compare/v1.0.5...v1.0.9

FEATURES.md

@@ -108,6 +108,31 @@ Blazouter is a comprehensive routing library for Blazor applications, available
 - Custom error handler registration via `AddBlazouterErrorHandler<T>()`
 - Error types: `ComponentLoadFailed`, `GuardRejected`, `NavigationFailed`, `InvalidRoute`
 
+### ✅ 11. Query String Helpers and Utilities
+- Tested and verified working
+- Type-safe query string manipulation with fluent API
+- `QueryStringBuilder` class for building query strings
+- Automatic URL encoding via `Uri.EscapeDataString`
+- Safe parsing with `TryParse` and default value support
+- Comprehensive XML documentation with code examples
+- `RouterStateExtensions` for typed query parameter parsing
+  - `HasQuery()` to check parameter existence
+  - `GetAllQueryParams()` to retrieve all parameters as dictionary
+  - Nullable variants: `GetQueryIntOrNull()`, `GetQueryBoolOrNull()`, etc.
+  - `GetQueryBool()` supporting "true", "false", "1", "0", "yes", "no", "on", "off"
+  - `GetQueryDateTime()`, `GetQueryGuid()`, `GetQueryEnum<T>()` for complex types
+  - `GetQueryInt()`, `GetQueryLong()`, `GetQueryDecimal()`, `GetQueryDouble()` with default values
+- 15 `Set()` method overloads for replacing values without duplicates
+- `RouterNavigationExtensions` for enhanced navigation with query strings
+  - `NavigateToWithQuery()` - Fluent query builder integration
+  - `NavigateToWithClearedQuery()` - Clear all query parameters
+  - `NavigateToWithRemovedQuery()` - Remove specific parameters
+  - `NavigateToWithReplacedQuery()` - Replace all query parameters
+  - `NavigateToWithSingleQuery()` - Convenience for single parameter
+  - `NavigateToWithUpdatedQuery()` - Update specific parameters, preserve others
+- Sample application demonstrates all features in Navigation.razor and UserList.razor
+- 15 `Add()` method overloads for all common types (string, int, long, decimal, double, bool, DateTime, Guid, enum, and nullable variants)
+
 ## Components
 
 ### Router
@@ -175,6 +200,46 @@ Nested route renderer that:
 - Error handling interface for custom implementations
 - Registered as scoped service via AddBlazouterErrorHandler<T>()
 
+## Utilities
+
+### QueryStringBuilder
+- Fluent API for building query strings
+- Support for nullable variants of all types
+- `AddIf()` for conditional parameter addition
+- `AddRange()` for multiple values per parameter
+- `Build()` returns query string without `?` prefix
+- `Remove()` and `Clear()` for parameter removal
+- 15 type-safe `Set()` methods for replacing values
+- Automatic URL encoding with Uri.EscapeDataString
+- 15 type-safe `Add()` methods for appending values
+- `BuildWithPrefix()` returns query string with `?` prefix
+- `ToDictionary()` converts to Dictionary<string, string>
+- Support for string, int, long, decimal, double, bool, DateTime, Guid, enum types
+
+## Extension Methods
+
+### RouterStateExtensions
+- `HasQuery()` - Check if parameter exists
+- `GetQueryBoolOrNull()` - Parse nullable boolean
+- All methods use InvariantCulture for consistent parsing
+- `GetAllQueryParams()` - Get all parameters as dictionary
+- `GetQueryArray()` - Get multiple values for same parameter
+- `GetQueryGuid()`, `GetQueryGuidOrNull()` - Parse Guid parameters
+- `GetQueryEnum<T>()`, `GetQueryEnumOrNull<T>()` - Parse enum parameters
+- `GetQueryDateTime()`, `GetQueryDateTimeOrNull()` - Parse DateTime in ISO 8601 format
+- `GetQueryBool()` - Parse boolean with support for "true", "false", "1", "0", "yes", "no", "on", "off"
+- `GetQueryInt()`, `GetQueryLong()`, `GetQueryDecimal()`, `GetQueryDouble()` - Parse numeric parameters with defaults
+- `GetQueryIntOrNull()`, `GetQueryLongOrNull()`, `GetQueryDecimalOrNull()`, `GetQueryDoubleOrNull()` - Parse nullable numeric parameters
+
+### RouterNavigationExtensions
+- `NavigateToWithQuery()` - Navigate with fluent query builder
+- `NavigateToWithClearedQuery()` - Clear all query parameters
+- `NavigateToWithReplacedQuery()` - Replace all query parameters
+- `NavigateToWithRemovedQuery()` - Remove specific parameters by key
+- `NavigateToWithSingleQuery()` - Convenience method for single string parameter
+- `NavigateToWithSingleQuery<T>()` - Convenience method for single typed parameter
+- `NavigateToWithUpdatedQuery()` - Update specific parameters while preserving others
+
 ## Configuration
 
 ### RouteConfig Properties
@@ -200,12 +265,15 @@ Nested route renderer that:
 - Layout system support (DefaultLayout, per-route Layout)
 - CSS animations included (blazouter.css, blazouter.min.css)
 - All routing components (Router, RouterLink, RouterOutlet)
+- Fluent query string building with automatic URL encoding
 - Multi-framework support (net6.0, net7.0, net8.0, net9.0, net10.0)
+- Type-safe query parameter parsing with 15+ extension methods
 - Navigation services (RouterNavigationService, RouterStateService)
 - Route guards interface (IRouteGuard, AuthGuard base implementation)
 - Route configuration and matching (RouteConfig, RouteMatcherService)
 - Attribute-based routing (RouteAttributeDiscoveryService, 8 route attributes)
 - Error handling (IRouterErrorHandler, DefaultRouterErrorHandler, RouterErrorContext)
+- Query string utilities (QueryStringBuilder, RouterStateExtensions, RouterNavigationExtensions)
 
 ### Blazouter.Server
 - Server-side route optimization
@@ -234,6 +302,11 @@ The sample application demonstrates:
 3. About page with library information
 4. Lazy loaded page with component loader
 5. Users page with nested routing (list and detail views)
+6. Navigation page with comprehensive query string utilities showcase
+   - Type-safe query parameter parsing examples
+   - Traditional vs fluent query string building comparison
+   - Query parameter manipulation (update, remove, clear)
+   - Interactive buttons demonstrating all query string features
 
 All features are interactive and can be tested by navigating through the application.
 
@@ -250,4 +323,5 @@ All features are interactive and can be tested by navigating through the applica
 | Nested Routes | ❌ Limited | ✅ Unlimited nesting depth |
 | Attribute Routes | ❌ @page only | ✅ 8 attribute types with full config |
 | Parameter Access | ✅ Basic | ✅ Enhanced with RouterStateService |
-| Programmatic Nav | ✅ Basic | ✅ Enhanced with RouterNavigationService |
+| Programmatic Nav | ✅ Basic | ✅ Enhanced with RouterNavigationService |
+| Query String Helpers | ❌ Manual parsing | ✅ Type-safe fluent API with 15+ methods |

README.md

@@ -45,6 +45,7 @@ Blazouter addresses the limitations of traditional Blazor routing:
 - **📐 Layout System**: Flexible layout management with default and per-route layouts
 - **🔗 Programmatic Navigation**: Navigate imperatively with enhanced navigation service
 - **⚠️ Error Handling**: Comprehensive error handling with custom error handlers and retry mechanisms
+- **🔧 Query String Utilities**: Type-safe query string builder and typed parameter parsing with fluent API
 - **🎨 Route Transitions**: Beautiful animations when navigating between routes with 14 built-in transition types
 
 ## 📦 Available Packages
@@ -544,6 +545,65 @@ new RouteConfig
 }
 ```
 
+### Query String Utilities
+
+Blazouter provides comprehensive query string helpers for type-safe parameter handling:
+
+**Type-safe query parameter parsing:**
+
+```razor
+@using Blazouter.Extensions
+@inject RouterStateService RouterState
+
+@code {
+    protected override void OnInitialized()
+    {
+        // Typed parsing with defaults
+        int page = RouterState.GetQueryInt("page", 1);
+        bool active = RouterState.GetQueryBool("active", false);
+        DateTime? date = RouterState.GetQueryDateTimeOrNull("date");
+        
+        // Get all query parameters
+        var allParams = RouterState.GetAllQueryParams();
+    }
+}
+```
+
+**Fluent query string building:**
+
+```csharp
+@using Blazouter.Utilities
+@inject RouterNavigationService NavService
+
+@code {
+    private void NavigateWithQuery()
+    {
+        // Build query strings with type safety
+        NavService.NavigateToWithQuery("/search", q => q
+            .Add("term", "blazor")
+            .Add("active", true)
+            .Add("page", 2));
+    }
+}
+```
+
+**Update query parameters:**
+
+```csharp
+// Replace specific parameters while keeping others
+NavService.NavigateToWithUpdatedQuery(RouterState, null, q => q
+    .Set("page", currentPage + 1)
+    .Set("sort", "name"));
+
+// Remove parameters
+NavService.NavigateToWithRemovedQuery(RouterState, "filter", "sort");
+
+// Clear all parameters
+NavService.NavigateToWithClearedQuery(RouterState);
+```
+
+The `QueryStringBuilder` supports 15 type overloads including: string, int, long, decimal, double, bool, DateTime, Guid, enum, and their nullable variants.
+
 ## 🎨 Route Transitions
 
 Blazouter includes 14 built-in transitions for beautiful page navigation:
@@ -621,10 +681,10 @@ builder.Services.AddBlazouterErrorHandler<CustomRouterErrorHandler>();
 
 ### Error Types
 
-- `ComponentLoadFailed` - Component failed to load
+- `InvalidRoute` - Invalid route configuration
 - `GuardRejected` - Route guard denied access
 - `NavigationFailed` - Navigation operation failed
-- `InvalidRoute` - Invalid route configuration
+- `ComponentLoadFailed` - Component failed to load
 
 ## 🏗️ Project Structure
 
@@ -635,11 +695,12 @@ Blazouter/
 │   │   ├── Attributes/            # Route attribute definitions
 │   │   ├── Components/            # Router components (Router, RouterLink, RouterOutlet)
 │   │   │   └── Layouts/           # Built-in layout components
-│   │   ├── Extensions/            # Service collection extensions
+│   │   ├── Extensions/            # Service collection and router extensions (typed query parameters, navigation)
 │   │   ├── Guards/                # Route guard interfaces
 │   │   ├── Models/                # Route models (RouteConfig, RouteMatch, RouteTransition)
 │   │   ├── Resources/             # Embedded resources
 │   │   ├── Services/              # Routing services (RouterStateService, RouteMatcherService, etc.)
+│   │   ├── Utilities/             # Query string builder and helper utilities
 │   │   └── wwwroot/               # CSS and assets (blazouter.css, blazouter.min.css)
 │   ├── Blazouter.Server/          # Server-specific extensions
 │   │   ├── Extensions/            # Server integration (AddBlazouterSupport)
@@ -733,7 +794,7 @@ Inspired by React Router and built to bring similar capabilities to the Blazor e
 - [ ] Route middleware support
 - [ ] Performance optimizations
 - [ ] Advanced caching strategies
-- [ ] Query string helpers and utilities
+- [x] Query string helpers and utilities
 - [ ] Better TypeScript integration for JS interop
 
 ## ⭐ Show Your Support

samples/Blazouter.Hybrid.Sample/Blazouter.Hybrid.Sample.csproj

@@ -70,6 +70,7 @@
     </ItemGroup>
 
     <ItemGroup>
+        <None Include="bun.lock" Visible="false" />
         <None Include="package.json" Visible="false" />
         <None Include="Tailwind.txt" Visible="false" />
         <None Include="postcss.config.mjs" Visible="false" />