Public/State.ps1
|
<#
.SYNOPSIS Sets an object within the shared state. .DESCRIPTION Sets an object within the shared state. .PARAMETER Name The name of the state object. .PARAMETER Value The value to set in the state. .PARAMETER Scope An optional Scope for the state object, used when saving the state. .EXAMPLE Set-PodeState -Name 'Data' -Value @{ 'Name' = 'Rick Sanchez' } .EXAMPLE Set-PodeState -Name 'Users' -Value @('user1', 'user2') -Scope General, Users #> function Set-PodeState { [CmdletBinding()] [OutputType([object])] param( [Parameter(Mandatory=$true)] [string] $Name, [Parameter(ValueFromPipeline=$true)] [object] $Value, [Parameter()] [string[]] $Scope ) if ($null -eq $PodeContext.Server.State) { throw "Pode has not been initialised" } if ($null -eq $Scope) { $Scope = @() } $PodeContext.Server.State[$Name] = @{ Value = $Value Scope = $Scope } return $Value } <# .SYNOPSIS Retrieves some state object from the shared state. .DESCRIPTION Retrieves some state object from the shared state. .PARAMETER Name The name of the state object. .PARAMETER WithScope If supplied, the state's value and scope will be returned as a hashtable. .EXAMPLE Get-PodeState -Name 'Data' #> function Get-PodeState { [CmdletBinding()] param( [Parameter(Mandatory=$true)] [string] $Name, [switch] $WithScope ) if ($null -eq $PodeContext.Server.State) { throw "Pode has not been initialised" } if ($WithScope) { return $PodeContext.Server.State[$Name] } else { return $PodeContext.Server.State[$Name].Value } } <# .SYNOPSIS Returns the current names of state variables. .DESCRIPTION Returns the current names of state variables that have been set. You can filter the result using Scope or a Pattern. .PARAMETER Pattern An optional regex Pattern to filter the state names. .PARAMETER Scope An optional Scope to filter the state names. .EXAMPLE $names = Get-PodeStateNames -Scope '<scope>' .EXAMPLE $names = Get-PodeStateNames -Pattern '^\w+[0-9]{0,2}$' #> function Get-PodeStateNames { [CmdletBinding()] param( [Parameter()] [string] $Pattern, [Parameter()] [string[]] $Scope ) if ($null -eq $PodeContext.Server.State) { throw "Pode has not been initialised" } if ($null -eq $Scope) { $Scope = @() } $tempState = $PodeContext.Server.State.Clone() $keys = $tempState.Keys if ($Scope.Length -gt 0) { $keys = @(foreach($key in $keys) { if ($tempState[$key].Scope -iin $Scope) { $key } }) } if (![string]::IsNullOrWhiteSpace($Pattern)) { $keys = @(foreach($key in $keys) { if ($key -imatch $Pattern) { $key } }) } return $keys } <# .SYNOPSIS Removes some state object from the shared state. .DESCRIPTION Removes some state object from the shared state. After removal, the original object being stored is returned. .PARAMETER Name The name of the state object. .EXAMPLE Remove-PodeState -Name 'Data' #> function Remove-PodeState { [CmdletBinding()] [OutputType([object])] param( [Parameter(Mandatory=$true)] [string] $Name ) if ($null -eq $PodeContext.Server.State) { throw "Pode has not been initialised" } $value = $PodeContext.Server.State[$Name].Value $null = $PodeContext.Server.State.Remove($Name) return $value } <# .SYNOPSIS Saves the current shared state to a supplied JSON file. .DESCRIPTION Saves the current shared state to a supplied JSON file. When using this function, it's recommended to wrap it in a Lock-PodeObject block. .PARAMETER Path The path to a JSON file which the current state will be saved to. .PARAMETER Scope An optional array of scopes for state objects that should be saved. (This has a lower precedence than Exclude/Include) .PARAMETER Exclude An optional array of state object names to exclude from being saved. (This has a higher precedence than Include) .PARAMETER Include An optional array of state object names to only include when being saved. .PARAMETER Compress If supplied, the saved JSON will be compressed. .EXAMPLE Save-PodeState -Path './state.json' .EXAMPLE Save-PodeState -Path './state.json' -Exclude Name1, Name2 .EXAMPLE Save-PodeState -Path './state.json' -Scope Users #> function Save-PodeState { [CmdletBinding()] param( [Parameter(Mandatory=$true)] [string] $Path, [Parameter()] [string[]] $Scope, [Parameter()] [string[]] $Exclude, [Parameter()] [string[]] $Include, [switch] $Compress ) # error if attempting to use outside of the pode server if ($null -eq $PodeContext.Server.State) { throw "Pode has not been initialised" } # get the full path to save the state $Path = Get-PodeRelativePath -Path $Path -JoinRoot # contruct the state to save (excludes, etc) $state = $PodeContext.Server.State.Clone() # scopes if (($null -ne $Scope) -and ($Scope.Length -gt 0)) { foreach ($_key in $state.Clone().Keys) { # remove if no scope if (($null -eq $state[$_key].Scope) -or ($state[$_key].Scope.Length -eq 0)) { $null = $state.Remove($_key) continue } # check scopes (only remove if none match) $found = $false foreach ($_scope in $state[$_key].Scope) { if ($Scope -icontains $_scope) { $found = $true break } } if ($found) { continue } # none matched, remove $null = $state.Remove($_key) } } # include keys if (($null -ne $Include) -and ($Include.Length -gt 0)) { foreach ($_key in $state.Clone().Keys) { if ($Include -inotcontains $_key) { $null = $state.Remove($_key) } } } # exclude keys if (($null -ne $Exclude) -and ($Exclude.Length -gt 0)) { foreach ($_key in $state.Clone().Keys) { if ($Exclude -icontains $_key) { $null = $state.Remove($_key) } } } # save the state $null = ConvertTo-Json -InputObject $state -Depth 10 -Compress:$Compress | Out-File -FilePath $Path -Force } <# .SYNOPSIS Restores the shared state from some JSON file. .DESCRIPTION Restores the shared state from some JSON file. .PARAMETER Path The path to a JSON file that contains the state information. .PARAMETER Merge If supplied, the state loaded from the JSON file will be merged with the current state, instead of overwriting it. .EXAMPLE Restore-PodeState -Path './state.json' #> function Restore-PodeState { [CmdletBinding()] param( [Parameter(Mandatory=$true)] [string] $Path, [switch] $Merge ) # error if attempting to use outside of the pode server if ($null -eq $PodeContext.Server.State) { throw "Pode has not been initialised" } # get the full path to the state $Path = Get-PodeRelativePath -Path $Path -JoinRoot if (!(Test-Path $Path)) { return } # restore the state from file $state = @{} if (Test-PodeIsPSCore) { $state = (Get-Content $Path -Force | ConvertFrom-Json -AsHashtable -Depth 10) } else { $props = (Get-Content $Path -Force | ConvertFrom-Json).psobject.properties foreach ($prop in $props) { $state[$prop.Name] = $prop.Value } } # check for no scopes, and add for backwards compat $convert = $false foreach ($_key in $state.Clone().Keys) { if ($null -eq $state[$_key].Scope) { $convert = $true break } } if ($convert) { foreach ($_key in $state.Clone().Keys) { $state[$_key] = @{ Value = $state[$_key] Scope = @() } } } # set the scope to the main context if ($Merge) { foreach ($_key in $state.Clone().Keys) { $PodeContext.Server.State[$_key] = $state[$_key] } } else { $PodeContext.Server.State = $state.Clone() } } <# .SYNOPSIS Tests if the shared state contains some state object. .DESCRIPTION Tests if the shared state contains some state object. .PARAMETER Name The name of the state object. .EXAMPLE Test-PodeState -Name 'Data' #> function Test-PodeState { [CmdletBinding()] [OutputType([bool])] param( [Parameter(Mandatory=$true)] [string] $Name ) if ($null -eq $PodeContext.Server.State) { throw "Pode has not been initialised" } return $PodeContext.Server.State.ContainsKey($Name) } |