AIOS Timer System - How To Use
=================================
Version: 1.0.0
Author: Poorkingz

QUICK START
-----------
local Timers = AIOS.Timers

-- One-shot timer (fires once after delay)
Timers:After(2.5, function()
    print("Fired after 2.5 seconds")
end)

-- Repeating timer (fires every interval)
local h = Timers:Every(1.0, function()
    print("Tick every second")
end)

-- Cancel the repeating timer later
Timers:Cancel(h.id)

NAMED TIMERS
------------
-- Use Schedule() when you need a name for cancellation
Timers:Schedule("BossAlert", 5.0, function()
    print("Boss spawning!")
end)

-- Cancel by name
Timers:Cancel("BossAlert")

-- Named repeating
Timers:ScheduleRepeating("HealthCheck", 2.0, function()
    print("Checking health...")
end)

THROTTLE & DEBOUNCE
-------------------
-- Throttle: only runs once per delay window
Timers:Throttle("ScanAH", 1.0, function()
    print("Scanning auction house...")
end)

-- Debounce: resets timer on each call (good for resize events)
Timers:Debounce("ResizeUI", 0.3, function()
    print("UI resized - updating layout")
end)

GROUP MANAGEMENT
----------------
-- Register timers to groups for bulk control
local t1 = Timers:After(5.0, function() end)
local t2 = Timers:After(5.0, function() end)

Timers:RegisterToGroup("Combat", t1)
Timers:RegisterToGroup("Combat", t2)

-- Pause all timers in a group
Timers:PauseGroup("Combat")

-- Resume them
Timers:ResumeGroup("Combat")

-- Cancel entire group
Timers:CancelGroup("Combat")

CANCELLATION
------------
Timers:Cancel("timer_id")           -- cancel one
Timers:CancelAll()                   -- cancel everything
Timers:CancelPattern("Boss")         -- cancel by substring match
Timers:CancelGroup("Combat")         -- cancel by group

QUEUE (SEQUENTIAL TIMERS)
-------------------------
-- Enqueue timers that run in order
Timers:Enqueue("Step1", 1.0, function()
    print("Step 1 done")
end)

Timers:Enqueue("Step2", 1.0, function()
    print("Step 2 done")
end, false, 1)  -- priority (lower = earlier)

Timers:ClearQueue()  -- clear all queued

SLASH COMMANDS
--------------
/aiosdevtimers list       -- show active & queued timers
/aiosdevtimers clear      -- cancel all + clear queue
/aiosdevtimers debug      -- toggle debug logging

/aiostimersprof on        -- enable profiler
/aiostimersprof off       -- disable profiler
/aiostimersprof stats     -- show latency stats
/aiostimersprof reset     -- reset stats

/aiosqueue list           -- show queued timers
/aiosqueue clear          -- clear queue

/aiostimergroups list     -- show groups
/aiostimergroups pause <name>
/aiostimergroups resume <name>
/aiostimergroups cancel <name>
/aiostimergroups remove <name>

EVENTS EMITTED
--------------
AIOS_Timers_Scheduled     -- (id, delay)
AIOS_Timers_Fired         -- (id)
AIOS_Timers_Cancelled     -- (id or "ALL")
TimerCanceledPattern      -- (pattern, count)
TimerCanceledGroup        -- (group, count)
TimerQueued               -- (id, delay, repeating)
TimerQueueCleared         -- (count)

Listen to these via EventBus:
EventBus:Listen("AIOS_Timers_Fired", function(id)
    print("Timer fired:", id)
end)

EXAMPLE: COMBAT TIMER
---------------------
local function StartCombatTimer()
    Timers:Schedule("CombatDuration", 0, function() end)
    Timers:Every(1.0, function()
        combatTime = combatTime + 1
        print("Combat time: " .. combatTime .. "s")
    end)
end

local function EndCombat()
    Timers:CancelAll()
end

EXAMPLE: COOLDOWN TRACKER
-------------------------
local cooldowns = {}

function TrackCooldown(spell, duration)
    cooldowns[spell] = true
    Timers:After(duration, function()
        cooldowns[spell] = nil
        print(spell .. " ready!")
    end)
end

TrackCooldown("Fireball", 3.0)

IMPORTANT NOTES
---------------
- All callbacks are wrapped in pcall(). Errors are logged but won't crash.
- Anonymous timers (After/Every) use the frame loop.
- Named timers (Schedule/ScheduleRepeating) use C_Timer.After internally.
- Cancelled timers are removed from ActiveTimers immediately.
- Repeating timers run until Cancel() is called.
- Throttle keys are global strings. Use addon-specific prefixes to avoid collisions.
