.destroy() — Full Cleanup and Shutdown

Quick Start (30 seconds)

// Shut down a specific helper completely
Elements.destroy();

// Or shut down everything at once
DOMHelpers.destroyAll();

---

What is .destroy()?

.destroy() performs a complete shutdown of a helper. It:

1. Empties the cache
2. Disconnects the MutationObserver (stops watching for DOM changes)
3. Clears the cleanup timer (stops scheduled cache scans)
4. Marks the helper as destroyed

After calling .destroy(), the helper stops working. It won't cache new lookups, it won't watch for DOM changes, and it won't perform automatic cleanups.

Simply put, .destroy() is the off switch.

---

Syntax

Elements.destroy()       // Shuts down the Elements helper
Collections.destroy()    // Shuts down the Collections helper
Selector.destroy()       // Shuts down the Selector helper

Parameters: None

Returns: undefined

---

Why Does .destroy() Exist?

Every helper runs background processes that consume resources:

Running helper resources:
┌────────────────────────────────────────┐
│  MutationObserver                      │
│  └── Watching every DOM change         │
│      └── Uses CPU on every mutation    │
│                                        │
│  Cleanup Timer                         │
│  └── Fires every 30 seconds           │
│      └── Scans the entire cache        │
│                                        │
│  Cache (Map)                           │
│  └── Holding references to elements    │
│      └── Uses memory                   │
└────────────────────────────────────────┘

In most apps, these resources are tiny and don't matter. But there are scenarios where you want to release them:

• Your single-page app navigates away from a section that used DOM Helpers
• Your app is shutting down and you want clean resource release
• You're running tests and need to tear down between test cases
• You're working in a memory-constrained environment

---

How Does It Work?

Here's exactly what happens when you call .destroy():

Elements.destroy()
   ↓
1️⃣  isDestroyed = true
    └── Helper marks itself as shut down
   ↓
2️⃣  MutationObserver.disconnect()
    └── Stops watching the DOM for changes
    └── observer = null
   ↓
3️⃣  clearTimeout(cleanupTimer)
    └── Cancels the next scheduled cleanup
    └── cleanupTimer = null
   ↓
4️⃣  cache.clear()
    └── Removes all cached references
   ↓
Done. Helper is fully shut down.

What Gets Destroyed

Resource	What Happens
Cache (Map)	Emptied — all entries removed
MutationObserver	Disconnected — stops watching DOM changes
Cleanup Timer	Cleared — no more scheduled scans
isDestroyed flag	Set to true

What Remains

Stays	Why
The helper object itself	Still exists in memory, but non-functional
Stats counters	hits, misses keep their last values
Configuration	Settings still stored, but not actively used

---

Basic Usage

Example 1: App Shutdown

function shutdownApp() {
  // Save user data
  saveUserData();

  // Release all DOM Helpers resources
  Elements.destroy();
  Collections.destroy();
  Selector.destroy();

  console.log('All helpers shut down');
}

// Or use the shortcut
function shutdownApp() {
  saveUserData();
  DOMHelpers.destroyAll();  // Destroys all three at once
}

---

Example 2: SPA Section Teardown

// When leaving a section in a single-page app
function leaveAdminPanel() {
  // Clean up resources used by admin panel
  Elements.destroy();

  // Remove admin panel DOM
  document.getElementById('adminPanel').remove();

  // Navigate to another section
  loadHomePage();
}

---

Example 3: Test Cleanup

// In a testing environment
describe('My Component', () => {
  afterEach(() => {
    // Clean up after each test
    DOMHelpers.destroyAll();
  });

  it('should update the header', () => {
    Elements.header.update({ textContent: 'Test' });
    // ...assertions...
  });
});

---

Automatic Destruction on Page Unload

The library automatically calls destroyAll() when the page is about to unload:

// This is built into the library — you don't need to add it
window.addEventListener('beforeunload', () => {
  DOMHelpers.destroyAll();
});

This means in most apps, you never need to call .destroy() manually. The library cleans up after itself when the user navigates away or closes the tab.

---

What Happens After .destroy()?

After destruction, the helper's background systems are shut down:

// Before destroy
Elements.header;  // Works — cached lookup
Elements.stats(); // Returns performance data

// Destroy
Elements.destroy();

// After destroy — background systems are off
// The MutationObserver no longer watches for new elements
// The cleanup timer no longer runs
// The cache is empty and won't auto-rebuild

---

.destroy() vs .clear() — The Key Difference

               .clear()                          .destroy()
        ┌──────────────────┐              ┌──────────────────┐
Cache:  │    Emptied       │              │    Emptied       │
        ├──────────────────┤              ├──────────────────┤
Observer│    Running ✅    │              │    Stopped ❌    │
        ├──────────────────┤              ├──────────────────┤
Timer:  │    Running ✅    │              │    Stopped ❌    │
        ├──────────────────┤              ├──────────────────┤
Result: │  Cache refreshed │              │  Helper shut down│
        │  Helper works    │              │  Helper stopped  │
        └──────────────────┘              └──────────────────┘

Question	.clear()	.destroy()
"I want fresh lookups but keep using the helper"	✅ Use this
"I'm done with this helper entirely"		✅ Use this
"My app is shutting down"		✅ Use this
"I replaced some HTML content"	✅ Use this

---

Common Pitfall: Using a Helper After Destroying It

// ❌ The helper's background systems won't function after destroy
Elements.destroy();
Elements.header;  // May still do a basic DOM lookup, but:
                  // - No MutationObserver to track changes
                  // - No cleanup timer to remove stale entries
                  // - No automatic cache rebuilding

// ✅ If you need the helper again, use clear() instead
Elements.clear();
Elements.header;  // Works normally — cache rebuilds, observer runs

Key Insight: .destroy() is a one-way operation. Once a helper is destroyed, you can't "un-destroy" it without reloading the page. If you just need a fresh start, use .clear() instead.

---

When to Use .destroy()

Scenario	Recommendation
Page unload / tab close	Automatic — library handles it
SPA route change (major section removed)	✅ Consider .destroy()
Test cleanup (afterEach)	✅ Good practice
Temporary cache issues	❌ Use .clear() instead
After AJAX content load	❌ Use .clear() instead
Memory optimization in long-running app	✅ If you're done with a helper

---

Summary

Aspect	Detail
What	Full shutdown — cache, observer, timer all stopped
When to use	App shutdown, section teardown, test cleanup
Automatic	Library calls destroyAll() on page unload — you rarely need this manually
Reversible?	No — once destroyed, the helper's background systems don't restart
Alternative	Use .clear() if you just want to empty the cache and keep using the helper

Simple Rule to Remember: .destroy() means "I'm done with this helper." Use .clear() if you just want a fresh start. In most apps, the library handles destruction automatically on page unload.