🚀 [Feature]: Add Get-Uri and Test-Uri function

.github/linters/.jscpd.json

@@ -0,0 +1,10 @@
+{
+    "threshold": 0,
+    "reporters": [
+        "consoleFull"
+    ],
+    "ignore": [
+        "**/tests/*"
+    ],
+    "absolute": true
+}

.github/workflows/Linter.yml

@@ -29,3 +29,4 @@ jobs:
           GITHUB_TOKEN: ${{ github.token }}
           VALIDATE_MARKDOWN_PRETTIER: false
           VALIDATE_YAML_PRETTIER: false
+          VALIDATE_JSON_PRETTIER: false

src/functions/public/ConvertFrom-UriQueryString.ps1

@@ -11,7 +11,7 @@
         back to their normal representation.
 
         .EXAMPLE
-        ConvertFrom-UriQueryString -QueryString 'name=John%20Doe&age=30&age=40'
+        ConvertFrom-UriQueryString -Query 'name=John%20Doe&age=30&age=40'
 
         Output:
         ```powershell
@@ -25,7 +25,7 @@
         values are decoded parameter values.
 
         .EXAMPLE
-        ConvertFrom-UriQueryString '?q=PowerShell%20URI'
+        '?q=PowerShell%20URI' | ConvertFrom-UriQueryString
 
         Output:
         ```powershell
@@ -44,12 +44,11 @@
     param(
         # The query string to parse. This can include the leading '?' or just the key-value pairs.
         # For example, both "?foo=bar&count=10" and "foo=bar&count=10" are acceptable.
-        [Parameter(Position = 0, ValueFromPipeline)]
+        [Parameter(ValueFromPipeline)]
         [AllowNull()]
         [string] $Query
     )
 
-    # Early exit if $Query is null or empty.
     if ([string]::IsNullOrEmpty($Query)) {
         Write-Verbose 'Query string is null or empty.'
         return @{}
@@ -60,9 +59,6 @@
     if ($Query.StartsWith('?')) {
         $Query = $Query.Substring(1)
     }
-    if ([string]::IsNullOrEmpty($Query)) {
-        return @{}  # return empty hashtable if no query present
-    }
 
     $result = @{}
     # Split by '&' to get each key=value pair

src/functions/public/Get-Uri.ps1

@@ -0,0 +1,134 @@
+function Get-Uri {
+    <#
+        .SYNOPSIS
+        Converts a string into a System.Uri, System.UriBuilder, or a normalized URI string.
+
+        .DESCRIPTION
+        The Get-Uri function processes a string and attempts to convert it into a valid URI.
+        It supports three output formats: a System.Uri object, a System.UriBuilder object,
+        or a normalized absolute URI string. If no scheme is present, "http://" is prefixed
+        to ensure a valid URI. The function enforces mutual exclusivity between the output
+        format parameters.
+
+        .EXAMPLE
+        Get-Uri -Uri 'example.com'
+
+        Output:
+        ```powershell
+        AbsolutePath   : /
+        AbsoluteUri    : http://example.com/
+        LocalPath      : /
+        Authority      : example.com
+        HostNameType   : Dns
+        IsDefaultPort  : True
+        IsFile         : False
+        IsLoopback     : False
+        PathAndQuery   : /
+        Segments       : {/}
+        IsUnc          : False
+        Host           : example.com
+        Port           : 80
+        Query          :
+        Fragment       :
+        Scheme         : http
+        OriginalString : http://example.com
+        DnsSafeHost    : example.com
+        IdnHost        : example.com
+        IsAbsoluteUri  : True
+        UserEscaped    : False
+        UserInfo       :
+        ```
+
+        Converts 'example.com' into a normalized absolute URI string.
+
+        .EXAMPLE
+        Get-Uri -Uri 'https://example.com/path' -AsUriBuilder
+
+        Output:
+        ```powershell
+        Scheme   : https
+        UserName :
+        Password :
+        Host     : example.com
+        Port     : 443
+        Path     : /path
+        Query    :
+        Fragment :
+        Uri      : https://example.com/path
+        ```
+
+        Returns a [System.UriBuilder] object for the specified URI.
+
+        .EXAMPLE
+        'example.com/path' | Get-Uri -AsString
+
+        Output:
+        ```powershell
+        http://example.com/path
+        ```
+
+        Returns a [string] with the full absolute URI.
+
+        .LINK
+        https://psmodule.io/Uri/Functions/Get-Uri
+    #>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSReviewUnusedParameter', 'AsString',
+        Scope = 'Function',
+        Justification = 'Present for parameter sets'
+    )]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSReviewUnusedParameter', 'AsUriBuilder',
+        Scope = 'Function',
+        Justification = 'Present for parameter sets'
+    )]
+    [OutputType(ParameterSetName = 'UriBuilder', [System.UriBuilder])]
+    [OutputType(ParameterSetName = 'String', [string])]
+    [OutputType(ParameterSetName = 'AsUri', [System.Uri])]
+    [CmdletBinding(DefaultParameterSetName = 'AsUri')]
+    param(
+        # The string representation of the URI to be processed.
+        [Parameter(Mandatory, Position = 0, ValueFromPipeline)]
+        [string] $Uri,
+
+        # Outputs a System.UriBuilder object.
+        [Parameter(Mandatory, ParameterSetName = 'AsUriBuilder')]
+        [switch] $AsUriBuilder,
+
+        # Outputs the URI as a normalized string.
+        [Parameter(Mandatory, ParameterSetName = 'AsString')]
+        [switch] $AsString
+    )
+
+    process {
+        $inputString = $Uri.Trim()
+        if ([string]::IsNullOrWhiteSpace($inputString)) {
+            throw 'The Uri parameter cannot be null or empty.'
+        }
+
+        # Attempt to create a System.Uri (absolute) from the string
+        $uriObject = $null
+        $success = [System.Uri]::TryCreate($inputString, [System.UriKind]::Absolute, [ref]$uriObject)
+        if (-not $success) {
+            # If no scheme present, try adding "http://"
+            if ($inputString -notmatch '^[A-Za-z][A-Za-z0-9+.-]*:') {
+                $success = [System.Uri]::TryCreate("http://$inputString", [System.UriKind]::Absolute, [ref]$uriObject)
+            }
+            if (-not $success) {
+                throw "The provided value '$Uri' cannot be converted to a valid URI."
+            }
+        }
+
+        switch ($PSCmdlet.ParameterSetName) {
+            'AsUriBuilder' {
+                return ([System.UriBuilder]::new($uriObject))
+            }
+            'AsString' {
+                return ($uriObject.GetComponents([System.UriComponents]::AbsoluteUri, [System.UriFormat]::SafeUnescaped))
+            }
+            'AsUri' {
+                return $uriObject
+            }
+        }
+    }
+}

src/functions/public/Test-Uri.ps1

@@ -0,0 +1,75 @@
+function Test-Uri {
+    <#
+        .SYNOPSIS
+        Validates whether a given string is a valid URI.
+
+        .DESCRIPTION
+        The Test-Uri function checks whether a given string is a valid URI. By default, it enforces absolute URIs.
+        If the `-AllowRelative` switch is specified, it allows both absolute and relative URIs.
+
+        .EXAMPLE
+        Test-Uri -Uri "https://example.com"
+
+        Output:
+        ```powershell
+        True
+        ```
+
+        Checks if `https://example.com` is a valid URI, returning `$true`.
+
+        .EXAMPLE
+        Test-Uri -Uri "invalid-uri"
+
+        Output:
+        ```powershell
+        False
+        ```
+
+        Returns `$false` for an invalid URI string.
+
+        .EXAMPLE
+        "https://example.com", "invalid-uri" | Test-Uri
+
+        Output:
+        ```powershell
+        True
+        False
+        ```
+
+        Accepts input from the pipeline and validates multiple URIs.
+
+        .OUTPUTS
+        [System.Boolean]
+
+        .NOTES
+        Returns `$true` if the input string is a valid URI, otherwise returns `$false`.
+
+        .LINK
+        https://psmodule.io/Uri/Functions/Test-Uri
+    #>
+    [OutputType([bool])]
+    [CmdletBinding()]
+    param(
+        # Accept one or more URI strings from parameter or pipeline.
+        [Parameter(Mandatory, ValueFromPipeline)]
+        [string] $Uri,
+
+        # If specified, allow valid relative URIs.
+        [Parameter()]
+        [switch] $AllowRelative
+    )
+
+    process {
+        # If -AllowRelative is set, try to create a URI using RelativeOrAbsolute.
+        # Otherwise, enforce an Absolute URI.
+        $uriKind = if ($AllowRelative) {
+            [System.UriKind]::RelativeOrAbsolute
+        } else {
+            [System.UriKind]::Absolute
+        }
+
+        # Try to create the URI. The out parameter is not used.
+        $dummy = $null
+        [System.Uri]::TryCreate($Uri, $uriKind, [ref]$dummy)
+    }
+}