Events

A priority-aware publish/subscribe event bus with wildcard matching, one-time listeners, and automatic cleanup. The event system underpins the router, state manager, and all inter-module communication in Aura.js.

Quick Start

Subscribe to events, emit them with data, and clean up when done.

js
import Aura from 'aurajs';

// Subscribe to an event
const unsub = Aura.on('user:login', (user) => {
  console.log('Welcome', user.name);
});

// Emit an event with data
Aura.emit('user:login', { name: 'Alice' });

// Unsubscribe when no longer needed
unsub();

on() core

Register a persistent listener for an event. Listeners are sorted by priority (higher values run first). Returns an unsubscribe function for easy cleanup.

Aura.on(event: string, fn: (...args: unknown[]) => void, priority?: number): () => void

Param	Type	Description
event	string	Event name. Supports namespaced names like `'user:login'`. Use `'namespace:*'` for wildcards.
fn	Function	Callback invoked with whatever arguments are passed to `emit()`.
priority	number	Optional priority (default `0`). Higher values execute first.

Returns a () => void unsubscribe function.

js
// Basic listener
const unsub = Aura.on('cart:update', (items) => {
  renderCart(items);
});

// High-priority listener (runs before default)
Aura.on('cart:update', (items) => {
  analytics.track('cart_updated', items.length);
}, 10);

// Cleanup later
unsub();

once() core

Register a one-time listener that is automatically removed after it fires once. Like on(), it supports priority ordering and returns an unsubscribe function (useful if you want to cancel before it fires).

Aura.once(event: string, fn: (...args: unknown[]) => void): () => void

Param	Type	Description
event	string	Event name to listen for.
fn	Function	Callback invoked once, then automatically removed.

Returns a () => void unsubscribe function.

js
// Only handle the first occurrence
Aura.once('app:ready', () => {
  console.log('Application is ready!');
});

// Cancel before it fires
const cancel = Aura.once('timeout:warning', showWarning);
// Changed our mind
cancel();

off() core

Remove event listeners. Pass a specific function reference to remove just that listener, or omit fn to remove all listeners for the event.

Aura.off(event: string, fn?: (...args: unknown[]) => void): void

Param	Type	Description
event	string	Event name to remove listeners from.
fn	Function	Optional. The specific listener to remove. If omitted, all listeners for the event are removed.

js
function onLogin(user) {
  console.log('Logged in:', user.name);
}

Aura.on('user:login', onLogin);

// Remove the specific listener
Aura.off('user:login', onLogin);

// Remove ALL listeners for an event
Aura.off('user:login');

emit() core

Fire an event, invoking all matching listeners in priority order. Also triggers any wildcard listeners whose pattern matches (e.g. 'user:*' matches 'user:login'). Any number of arguments can be passed and are forwarded to listeners.

Aura.emit(event: string, ...args: unknown[]): void

Param	Type	Description
event	string	The event name to fire.
...args	unknown[]	Any number of arguments forwarded to all matching listeners.

js
// Emit with no data
Aura.emit('app:ready');

// Emit with a single argument
Aura.emit('user:login', { name: 'Alice', id: 1 });

// Emit with multiple arguments
Aura.emit('form:error', 'email', 'Invalid email address');

Wildcard Patterns feature

Register listeners with a :* suffix to match all events in a namespace. When emit('user:login') is called, listeners registered on both 'user:login' (exact) and 'user:*' (wildcard) are invoked.

js
// Catch ALL user events
Aura.on('user:*', (...args) => {
  console.log('User event fired', args);
});

// All of these will trigger the wildcard listener above:
Aura.emit('user:login', userData);
Aura.emit('user:logout');
Aura.emit('user:updated', changes);

// Catch ALL route events
Aura.on('route:*', (...args) => {
  console.log('Route event', args);
});

Priority Ordering feature

Listeners are sorted by priority in descending order. Higher priority values run first. Default priority is 0. This is useful when certain listeners need to run before others (e.g. validation before rendering).

js
// Priority 100 - runs first
Aura.on('form:submit', (data) => {
  console.log('1. Validate');
}, 100);

// Priority 50 - runs second
Aura.on('form:submit', (data) => {
  console.log('2. Transform');
}, 50);

// Priority 0 (default) - runs last
Aura.on('form:submit', (data) => {
  console.log('3. Submit');
});

Aura.emit('form:submit', formData);
// Output: 1. Validate, 2. Transform, 3. Submit

Built-in Events reference

Aura.js modules emit the following events automatically. You can listen to any of them with Aura.on().

Router Events

Event	Payload	Description
route:change	RouteContext	A route handler completed successfully.
route:error	{ path, error }	A route handler threw an exception.
route:notFound	{ path }	No route matched the requested path (404).
route:stateChange	PageState	The page state transitioned (idle/loading/loaded/error).

State Events

Event	Payload	Description
state:<key>	newVal, oldVal	A specific state key was updated.
state:change	key, newVal, oldVal	Any state key was updated (outside of batch).
state:batch	[key, val, old][]	A batch of state changes completed.
state:reset	newState	The state was reset.

js
// Listen to all route events with a wildcard
Aura.on('route:*', (...args) => {
  console.log('[Router]', ...args);
});

// Listen to all state changes with a wildcard
Aura.on('state:*', (...args) => {
  console.log('[State]', ...args);
});

Patterns

Cleanup on route change

Use the returned unsubscribe function to clean up listeners when navigating away from a page.

js
let cleanups = [];

Aura.route('/dashboard', (ctx) => {
  // Clean up previous listeners
  cleanups.forEach(fn => fn());
  cleanups = [];

  // Set up new listeners
  cleanups.push(
    Aura.on('data:refresh', loadDashboard)
  );
  cleanups.push(
    Aura.on('notification:new', showBadge)
  );
});

Custom application events

Use namespaced event names to keep your custom events organized and take advantage of wildcard matching.

js
// Component A emits
Aura.emit('cart:add', { productId: 123, qty: 2 });
Aura.emit('cart:remove', { productId: 456 });

// Component B listens to all cart events
Aura.on('cart:*', (...args) => {
  updateCartUI();
});