Statistics & Cache Management — Introduction
Quick Start (30 seconds)
// Every helper has the same management methods
// Check performance
Elements.stats();
Collections.stats();
Selector.stats();
// Clear the cache
Elements.clear();
// Destroy the helper
Elements.destroy();
// Change settings
Elements.configure({ enableLogging: true });What is Cache Management?
Every helper in DOM Helpers — Elements, Collections, and Selector — uses an intelligent caching system. When you access an element or collection, the library stores a reference to it. The next time you access the same thing, it returns the stored reference instead of querying the DOM again.
This is what makes DOM Helpers fast. But caches need to be managed — they need monitoring, cleaning, and sometimes resetting.
That's where the cache management methods come in. Every helper has four methods that let you monitor and control its caching:
| Method | What It Does |
|---|---|
.stats() | Returns performance data — hits, misses, cache size, hit rate |
.clear() | Empties the cache — forces fresh DOM lookups |
.destroy() | Shuts down the helper — disconnects observers, clears timers, empties cache |
.configure(options) | Changes how the helper behaves — logging, cache size, cleanup frequency |
Why Does This Matter?
Without Caching
Every time you write Elements.header, the library could query the DOM:
Elements.header → document.getElementById('header') → DOM lookup
Elements.header → document.getElementById('header') → DOM lookup (again!)
Elements.header → document.getElementById('header') → DOM lookup (again!)DOM lookups aren't slow, but in a complex app with thousands of accesses, they add up.
With Caching (How DOM Helpers Actually Works)
Elements.header → DOM lookup → Cache it → Return element
Elements.header → Found in cache! → Return element (instant)
Elements.header → Found in cache! → Return element (instant)The first access queries the DOM. Every access after that returns the cached reference — no DOM query needed.
Mental Model: A Library's Card Catalog
Think of each helper's cache like a card catalog in a library:
┌──────────────────────────────────┐
│ Helper Cache │
│ (The Card Catalog) │
│ │
│ "header" → shelf 3, row 2 │
│ "footer" → shelf 5, row 1 │
│ "sidebar" → shelf 1, row 4 │
│ │
│ Instead of searching every │
│ shelf, you look up the card │
│ and go straight to the book. │
└──────────────────────────────────┘.stats()= Asking the librarian "How busy has it been? How many lookups vs direct finds?".clear()= Throwing away all the cards — the catalog is empty, but the library still works. New cards are created as books are found..destroy()= Closing the library entirely — no more lookups, no more catalog, no more staff..configure()= Telling the librarian "Keep only 500 cards max" or "Let me know every time someone looks up a book."
How the Cache System Works Behind the Scenes
Each helper runs three background systems to keep the cache healthy:
┌─────────────────────────────────────────────────┐
│ Helper Cache System │
│ │
│ 1. Cache (Map) │
│ ├── Stores element/collection references │
│ ├── Key: ID, selector, or "type:value" │
│ └── Evicts oldest when maxCacheSize reached │
│ │
│ 2. MutationObserver │
│ ├── Watches for DOM changes │
│ ├── Invalidates stale cache entries │
│ └── Debounced to avoid excessive processing │
│ │
│ 3. Cleanup Timer │
│ ├── Runs every cleanupInterval (30s default) │
│ ├── Scans for entries pointing to removed │
│ │ elements │
│ └── Removes stale entries automatically │
│ │
└─────────────────────────────────────────────────┘1️⃣ The Cache (Map) stores references to elements or collections you've accessed. When you look something up again, the cache returns it instantly.
2️⃣ The MutationObserver watches the DOM for changes — elements being added, removed, or having their attributes changed. When something changes, it invalidates the relevant cache entries so you never get stale references.
3️⃣ The Cleanup Timer periodically scans the cache for entries that point to elements no longer in the DOM. It removes them automatically to keep memory usage low.
These Methods Are Available on Every Helper
All three helpers — Elements, Collections, and Selector — have the same four methods:
// Elements
Elements.stats();
Elements.clear();
Elements.destroy();
Elements.configure({ enableLogging: true });
// Collections
Collections.stats();
Collections.clear();
Collections.destroy();
Collections.configure({ enableLogging: true });
// Selector
Selector.stats();
Selector.clear();
Selector.destroy();
Selector.configure({ enableLogging: true });They work the same way on each helper. The only differences are:
- What gets cached (IDs, class/tag/name collections, or CSS selector results)
- What the MutationObserver watches (ID changes, class/name changes, or general DOM changes)
- Extra options (Collections and Selector have
enableEnhancedSyntax; Selector hasenableSmartCaching)
Quick Comparison: The Four Methods
stats() clear() destroy() configure()
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
Purpose: │ Monitor │ │ Reset │ │ Shutdown │ │ Adjust │
│ the cache│ │ the cache│ │ entirely │ │ settings │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
Cache: Untouched Emptied Emptied Untouched
Observer: Running Running Stopped Running
Timer: Running Running Stopped Running
Helper: ✅ Works ✅ Works ❌ Stopped ✅ Works
Returns: Stats object undefined undefined Helper (chainable)What You'll Learn in This Section
The following pages cover each method in detail:
| Page | What It Covers |
|---|---|
| 02 — .stats() Deep Dive | Understanding every field in the stats object, reading hit rates, practical monitoring |
| 03 — .clear() | When and how to clear caches, what gets reset, what stays |
| 04 — .destroy() | Full shutdown — what gets cleaned up, when to use it |
| 05 — .configure() Options Reference | Every configuration option explained with examples |
| 06 — Auto-Cleanup & MutationObserver | How the automatic systems work behind the scenes |
| 07 — Practical Patterns & Debugging | Real-world debugging workflows, performance optimization |
Summary
| Concept | Key Takeaway |
|---|---|
| Why caching | Avoids repeated DOM queries — makes element access fast |
| Three background systems | Cache (Map), MutationObserver, Cleanup Timer |
| Four management methods | .stats(), .clear(), .destroy(), .configure() |
| Available on | Elements, Collections, and Selector — all three |
| Most important | The cache is automatic — you rarely need to manage it manually |
Simple Rule to Remember: The cache works automatically. Use
.stats()to monitor it,.clear()to reset it,.destroy()to shut it down, and.configure()to tune it.