V Vant Docs

Events

Unified event system: Event emitter, pub/sub, and job queue.

What

Vant includes an event system with:

Quick Start

Import events:

const event = require('./lib/event');
const { Event, PubSub, Queue } = event;

Event

Basic event emitter.

Create an event emitter:

const { Event } = require('./lib/event');

const emitter = new Event();

Emit

Emit an event:

emitter.emit('task:complete', { id: 123, result: 'done' });

Returns the number of handlers called.

On

Subscribe to events:

emitter.on('task:complete', (data) => {
    console.log('Task done:', data.id);
});

Once

One-time handler:

emitter.once('task:start', (data) => {
    console.log('Starting:', data.id);
});

Off

Unsubscribe:

function myHandler(data) { ... }
emitter.on('event', myHandler);
emitter.off('event', myHandler);

List

List registered events:

console.log(emitter.list());
// ['task:complete', 'task:start']

Stats

Get event stats:

console.log(emitter.stats());
// { events: 2, uptime: 5000 }

PubSub

Channel-based pub/sub with rooms.

Create a pub/sub:

const { PubSub } = require('./lib/qos').PubSub || require('./lib/event').PubSub;

const ps = new PubSub();

Subscribe

Subscribe to a channel:

ps.subscribe('notifications', (data) => {
    console.log('Got notification:', data);
});

Publish

Publish to a channel:

ps.publish('notifications', { message: 'hello' });

Rooms

Join/leave rooms:

ps.join('admin-room');
ps.leave('admin-room');

Stats

Get pub/sub stats:

console.log(ps.stats());
// { rooms: 1, listeners: 5, uptime: 5000 }

Queue

Background job queue.

Create a queue:

const { Queue } = require('./lib/event');

const queue = new Queue({
    concurrency: 3,  // max concurrent jobs
    timeout: 30000   // job timeout
});

Enqueue

Add a job:

const job = queue.enqueue('process', { data: 'hello' });
console.log(job.id);  // "job_abc123"
console.log(job.state); // "pending"

Process

Define job handler:

queue.process('process', async (job) => {
    console.log('Processing:', job.id);
    return { result: 'done' };
});

Events

Listen to job events:

queue.on('job:complete', (job) => {
    console.log('Job done:', job.id);
});

queue.on('job:failed', (job) => {
    console.log('Job failed:', job.error);
});

Job States

State What
pending Waiting to run
running Currently executing
completed Finished successfully
failed Finished with error

Options

Option Default What
concurrency 3 Max concurrent jobs
timeout 30000 Job timeout (ms)

Use Cases

Multi-Agent Communication

Agents communicate via events:

const event = require('./lib/event');

// Agent A publishes
event.emit('agent:a:done', { result: 'data' });

// Agent B subscribes
event.on('agent:a:done', (data) => {
    console.log('Got from A:', data.result);
});

Background Processing

Queue slow operations:

const { Queue } = require('./lib/event');

const queue = new Queue({ concurrency: 2 });

// Enqueue work
const job = queue.enqueue('email', {
    to: '[email protected]',
    subject: 'Hello',
    body: 'Message'
});

// Process
queue.process('email', async (job) => {
    await sendEmail(job.data);
});

Notifications

Pub/sub for notifications:

const ps = new PubSub();

ps.subscribe('alerts', (alert) => {
    console.log('Alert:', alert.message);
});

// Later
ps.publish('alerts', { message: 'High CPU' });

Integration

Events integrate with sandbox:

const sandbox = require('./lib/sandbox');

sandbox.on('blocked', (info) => {
    console.log('Blocked:', info.reason);
});