Firetron's UpdateOnInterval

--  ============================================================================
--    Firetron's UpdateOnInterval
--
--    Calls a function on an interval, and remembers the previous result between
--    the update intervals.
--    Works the same as OptimizedForInterval/DefineIntervalOptimization, but
--    with override feature.
--
--    Custom Command Dependencies:
--    None
--
--    Discord: @FiretronP75
--  ============================================================================

--  ========================================================
--    Variables
--  ========================================================

--  ------------------------------------
--    Definition
--  ------------------------------------

local dDefault
local dDescription
local dName
local dOutput
local dRequired
local dSuggestions
local dType

--  ------------------------------------
--    Function
--  ------------------------------------

local ConvertToEmptyIfNull
local GetNextResult
local GetNextTimestamp
local GetResult
local IsNextInterval
local IsUpdateNeeded

--  ------------------------------------
--    Key
--  ------------------------------------

local kLastResult    = 'LR'
local kLastTimestamp = 'LT'

--  ------------------------------------
--    Parameter
--  ------------------------------------

local pCommand
local pInterval
local pIsOverride

--  ========================================================
--    Command Definition
--  ========================================================

dName        = 'UpdateOnInterval'
dDescription = 'Calls a function on an interval, and remembers the previous result between the update intervals. '
             ..'Works the same as OptimizedForInterval/DefineIntervalOptimization, but with override feature.'
DefineCommand(dName, dDescription)

--  ========================================================
--    Parameter Definitions
--  ========================================================

dType        = CallbackType
dName        = 'command'
dDescription = 'The command or function to execute.'
dRequired    = true
dDefault     = function() end
dSuggestions = ''
pCommand = DefineParameter(dType, dName, dDescription, dRequired, dDefault, dSuggestions)

dType        = NumberType
dName        = 'interval'
dDescription = 'The interval in minutes at which the cached result will be updated with a new result from the command or function.'
dRequired    = true
dDefault     = 5
dSuggestions = ''
pInterval = DefineParameter(dType, dName, dDescription, dRequired, dDefault, dSuggestions)

dType        = BooleanType
dName        = 'override'
dDescription = 'If true, will immeidately update the result and restart the interval timer.'
dRequired    = true
dDefault     = false
dSuggestions = ''
pIsOverride = DefineParameter(dType, dName, dDescription, dRequired, dDefault, dSuggestions)

--  ========================================================
--    Functions
--  ========================================================

ConvertToEmptyIfNull = function (value)

  return IsNull(value)
     and { }
      or value

end

--  ----------------

GetNextResult = function ()

  local nextResult = pCommand()

  return ConvertToEmptyIfNull(nextResult)

end

--  ----------------

GetNextTimestamp = function ()

  return OpenTime(Time(), pInterval)

end

--  ----------------

GetResult = function ()

  local lastResult = Load(kLastResult, nil)

  if not IsUpdateNeeded(lastResult) then return lastResult end

  local result    = GetNextResult()
  local timestamp = GetNextTimestamp()

  Save(kLastResult,    result)
  Save(kLastTimestamp, timestamp)

  return result

end

--  ----------------

IsNextInterval = function ()

  local lastInterval = Load(kLastTimestamp, 0)

  local minutes      = pInterval * 60

  local nextInterval = lastInterval + minutes

  return Time() >= nextInterval

end

--  ----------------

IsUpdateNeeded = function (lastResult)

  return pIsOverride or IsNull(lastResult) or IsNextInterval()

end

--  ========================================================
--    Output Definition
--  ========================================================

dType        = ListDynamicType
dOutput      = { GetResult() }
dDescription = 'ListDynamic where the first element is the result or cached result of the given command or function.'
dSuggestions = ''
DefineOutput(dType, dOutput, dDescription, dSuggestions)