Skip to main content

Signal Internals (O(1) Engine)

Quantum Query is built on top of a "Micro-Signal" architecture. This is what enables its "9.2/10" senior-rated performance.

The Core Primitive: Signal<T>​

Unlike React's useState, which is bound to a specific component's lifecycle and re-render cycle, a Signal is an independent reactive value.

  • Storage: Signals live in the QueryStorage (a specialized LRU Cache).
  • Reactivity: We use @preact/signals-core for the underlying delivery mechanism.
  • Reference Stability: Every query key is mapped to a singleton signal instance.

Why O(1)?​

In a subscription-based model (like TanStack Query), when data changes:

  1. The library iterates through a list of observers.
  2. Each observer checks if it's still mounted.
  3. Each observer triggers a React state update.
  4. React reconciles the tree.

In Quantum's Fine-Grained model:

  1. The signal value is updated.
  2. The signal notifies its direct dependencies (the DOM nodes or hooks using the value).
  3. Only the specific parts of the UI that depend on the changed field are updated.

Memoization & Stability​

The QueryObserver uses a sophisticated computed block to derive the result object.

this.result$ = computed(() => {
  const entry = cacheSignal.get();
  // ... derive isLoading, isStale, etc.
  
  if (isDeepEqual(lastResult, nextResult)) {
    return lastResult; // Reference stability!
  }
  return nextResult;
});

This ensures that even if a signal "pings", your React component only re-renders if the meaningful data has changed. We call this "Reference Transparency".

Garbage Collection (GC)​

Signals are smart. They know when they are being watched.

  1. onActive: When the first component subscribes, the signal cancels any pending GC timer.
  2. onInactive: When the last component unmounts, the signal schedules a GC based on cacheTime.
  3. Automatic Cleanup: If the signal is never watched again, it is purged from memory, including any internal timers.