Performance

Measure execution time of synchronous and asynchronous operations, monitor memory usage, and collect performance logs. Entries that exceed an optional threshold are emitted as events. Access via Aura.perf.

Quick Start

js
import Aura from 'aura.js';

Aura.init();

// Listen for slow operations
Aura.perf.setThreshold(100); // only log entries > 100ms
Aura.on('perf:entry', entry => {
  console.warn(`Slow: ${entry.label} took ${entry.duration.toFixed(1)}ms`);
});

// Measure an async operation
const data = await Aura.perf.measure('fetchUsers', async () => {
  const res = await fetch('/api/users');
  return res.json();
});

// Manual start/end
Aura.perf.start('render');
renderPage();
const entry = Aura.perf.end('render');
console.log(entry?.duration);

setThreshold()

Sets a minimum duration threshold in milliseconds. When end() is called, entries with a duration below this threshold are discarded and not logged. Default is 0 (log everything).

setThreshold(ms: number): void

Param	Type	Description
ms	number	Minimum duration in milliseconds to record an entry

js
// Only capture entries slower than 50ms
Aura.perf.setThreshold(50);

// Reset to capture everything
Aura.perf.setThreshold(0);

start()

Begins a timing mark with the given label. Internally records a high-resolution timestamp via performance.now(). Pair with end() using the same label.

start(label: string): void

Param	Type	Description
label	string	A unique identifier for this timing measurement

js
Aura.perf.start('dom-update');

// ... perform work ...

const entry = Aura.perf.end('dom-update');

end()

Ends a timing mark started with start(). If the duration exceeds the threshold, a PerfEntry is recorded in the log and a perf:entry event is emitted. Returns null if no matching start mark exists or if the duration is below the threshold.

end(label: string): PerfEntry | null

Param	Type	Description
label	string	The label passed to `start()`

js
Aura.perf.start('computation');
heavyWork();
const entry = Aura.perf.end('computation');

if (entry) {
  console.log(`${entry.label}: ${entry.duration.toFixed(2)}ms`);
  console.log(`Recorded at: ${new Date(entry.timestamp).toISOString()}`);
}

measure()

A convenience wrapper that times a synchronous or asynchronous function. Automatically calls start() before and end() after execution. Returns the function's result. If the function throws, the timing is still recorded before the error is re-thrown.

async measure<T>(label: string, fn: () => T | Promise<T>): Promise<T>

Param	Type	Description
label	string	A unique identifier for this measurement
fn	() => T \| Promise<T>	The function to execute and time

js
// Measure an async fetch
const users = await Aura.perf.measure('loadUsers', async () => {
  const res = await fetch('/api/users');
  return res.json();
});

// Measure a synchronous operation
const sorted = await Aura.perf.measure('sort', () => {
  return bigArray.sort((a, b) => a - b);
});

getMemory()

Returns JavaScript heap memory usage via the non-standard performance.memory API (Chrome/Edge). Returns null in browsers that do not support it.

getMemory(): { used: number; total: number; limit: number } | null

js
const mem = Aura.perf.getMemory();

if (mem) {
  const usedMB = (mem.used / 1024 / 1024).toFixed(1);
  const totalMB = (mem.total / 1024 / 1024).toFixed(1);
  const limitMB = (mem.limit / 1024 / 1024).toFixed(1);
  console.log(`Heap: ${usedMB}/${totalMB} MB (limit: ${limitMB} MB)`);
}

getLogs()

Returns a shallow copy of all recorded performance entries. Entries are ordered chronologically by when end() was called.

getLogs(): PerfEntry[]

js
const logs = Aura.perf.getLogs();

logs.forEach(entry => {
  console.log(`${entry.label}: ${entry.duration.toFixed(2)}ms`);
});

// Find the slowest operation
const slowest = logs.sort((a, b) => b.duration - a.duration)[0];
console.log('Slowest:', slowest?.label);

clear()

Clears all recorded performance logs and any active timing marks.

clear(): void

js
// Reset everything
Aura.perf.clear();

console.log(Aura.perf.getLogs().length); // 0

Events

The performance module emits events through the Aura event system that you can listen to with Aura.on().

perf:entry

Emitted every time end() records an entry (i.e. the duration exceeds the threshold). The payload is a PerfEntry object.

js
Aura.on('perf:entry', entry => {
  // Send slow operations to your analytics
  if (entry.duration > 500) {
    reportToAnalytics({
      metric: entry.label,
      value: entry.duration,
      timestamp: entry.timestamp,
    });
  }
});

Types

PerfEntry

ts
interface PerfEntry {
  label: string;      // the identifier passed to start()/measure()
  duration: number;   // elapsed time in milliseconds
  timestamp: number;  // Date.now() when end() was called
}