#Vantage Core (@xtnd/vantage-core)

Package: @xtnd/vantage-core
Source Directory: xtnd-vantage/packages/core/

#1. Overview

@xtnd/vantage-core contains the foundational type definitions, interfaces, and the central VantageEventBus implementation upon which the entire XTND Vantage ecosystem is constructed.

It has zero external runtime dependencies, ensuring fast compilation, minimal bundle footprints, and maximum portability across Node.js, Cloudflare Workers, and all modern web browsers.

#2. Core Interfaces & Contracts (src/types.ts)

#EventPriority

export type EventPriority = 'P0_CRITICAL' | 'P1_HIGH' | 'P2_NORMAL' | 'P3_DEFERRED';

#VantageEvent<T>

export interface VantageEvent<T = any> {
  id: string;
  type: string;
  source: string;
  priority: EventPriority;
  timestamp: number;
  payload: T;
  meta?: {
    tenantId?: string;
    environment?: 'production' | 'staging' | 'development';
    version?: string;
    correlationId?: string;
    [key: string]: any;
  };
  synced?: boolean;
}

#IEventBus

export type EventHandler<T = any> = (event: VantageEvent<T>) => void | Promise<void>;
export type EventUnsubscribe = () => void;

export interface IEventBus {
  dispatch<T = any>(type: string, payload: T, options?: {
    source?: string;
    priority?: EventPriority;
    meta?: Record<string, any>;
  }): VantageEvent<T>;
  on<T = any>(type: string, handler: EventHandler<T>): EventUnsubscribe;
  once<T = any>(type: string, handler: EventHandler<T>): EventUnsubscribe;
  off<T = any>(type: string, handler: EventHandler<T>): void;
}

#IStorageAdapter

export interface IStorageAdapter {
  name: string;
  write(event: VantageEvent): Promise<void>;
  readUnsynced(limit?: number): Promise<VantageEvent[]>;
  markSynced(ids: string[]): Promise<void>;
  prune(beforeTimestamp?: number): Promise<number>;
  count(): Promise<number>;
  clear(): Promise<void>;
}

#IUrgencyEvaluator & ISyncTransport

export interface IUrgencyEvaluator {
  evaluate(type: string, payload: any, defaultPriority?: EventPriority): EventPriority;
  registerRule(rule: (type: string, payload: any) => EventPriority | null): void;
}

export interface ISyncTransport {
  sendImmediate(event: VantageEvent): Promise<boolean>;
  sendBatch(events: VantageEvent[]): Promise<{ success: boolean; syncedIds: string[] }>;
}

#3. The VantageEventBus Class (src/event-bus.ts)

VantageEventBus implements IEventBus with key operational capabilities:

#3.1 Wildcard Catch-All Listening (*)

Registering a listener for * captures all events emitted across the entire system. This is widely used by status logging widgets, audit logs, and developer consoles:

const bus = new VantageEventBus();

// Wildcard listener
const unsub = bus.on('*', (event) => {
  console.log(`[Global Audit] ${event.type} from ${event.source}`);
});

#3.2 Error Isolation

Listener execution is wrapped in a try...catch block. If an individual consumer throws an exception, it is caught and logged to console.error. The bus continues executing remaining handlers without interrupting the dispatch loop:

for (const handler of handlers) {
  try {
    handler(event);
  } catch (err) {
    console.error(`[VantageEventBus] Error in listener for event "${type}":`, err);
  }
}

#3.3 Universal UUID Generation

VantageEventBus uses crypto.randomUUID() when available (Node.js 16+, Cloudflare Workers, modern browsers) and gracefully falls back to a RFC4122 v4 pseudorandom generator for older browser environments.

#4. Usage Example

import { VantageEventBus } from '@xtnd/vantage-core';

const bus = new VantageEventBus('order-service');

// Listen for a specific event
const unsubscribe = bus.on('payment:completed', (event) => {
  console.log('Payment processed for order:', event.payload.orderId);
});

// Dispatch an event
const event = bus.dispatch('payment:completed', {
  orderId: 'ord_982341',
  amountUsd: 149.99
}, {
  priority: 'P1_HIGH',
  meta: { tenantId: 'tenant_asia_01' }
});

// Cleanup when done
unsubscribe();