QuarKernel

Event orchestration with dependency ordering, shared context, and state machines.

TypeScript-first. Zero dependencies. < 2KB gzipped.

Why QuarKernel?

// Other event libs: fire and pray
emitter.emit('user:login', data);

// QuarKernel: orchestrate with confidence
qk.on('user:login', fetchUser, { id: 'fetch' });
qk.on('user:login', logAnalytics, { after: ['fetch'] }); // Guaranteed order
qk.on('user:login', (e) => greet(e.context.user));       // Shared context

What makes it different:

| Feature | mitt | emittery | QuarKernel | |---------|:----:|:--------:|:--------------:| | Dependency ordering | - | - | Yes | | Shared context | - | - | Yes | | Composite events | - | - | Yes | | Wildcards | - | - | Yes | | Async/await | - | Yes | Yes | | TypeScript | Yes | Yes | Yes | | < 2KB | Yes | Yes | Yes |

Install

npm install @quazardous/quarkernel

<!-- CDN -->
<script src="https://unpkg.com/@quazardous/quarkernel@2/dist/index.umd.js"></script>

Quick Start

import { createKernel } from '@quazardous/quarkernel';

const qk = createKernel();

// 1. Dependency ordering - control execution sequence
qk.on('checkout', async (e) => {
  e.context.inventory = await checkStock(e.data.items);
}, { id: 'stock' });

qk.on('checkout', async (e) => {
  // Runs AFTER stock check - guaranteed
  await processPayment(e.data.card, e.context.inventory);
}, { after: ['stock'] });

await qk.emit('checkout', { items: ['sku-123'], card: 'tok_visa' });

// 2. Composite events - react to event combinations
import { Composition } from '@quazardous/quarkernel';

const checkout = new Composition([
  [qk, 'cart:ready'],
  [qk, 'payment:confirmed']
]);

checkout.onComposed(() => {
  console.log('Both events fired - proceed to shipping!');
});

// 3. Wildcards - catch event patterns
qk.on('user:*', (e) => console.log('User action:', e.name));
// Matches: user:login, user:logout, user:signup...

State Machines (FSM)

Built-in finite state machine support with XState-compatible format:

import { createMachine } from '@quazardous/quarkernel/fsm';

const order = createMachine({
  id: 'order',
  initial: 'draft',
  context: { items: 0 },
  states: {
    draft: { on: { SUBMIT: 'pending' } },
    pending: { on: { APPROVE: 'confirmed', REJECT: 'draft' } },
    confirmed: { on: { SHIP: 'shipped' } },
    shipped: {}
  },
  onEnter: {
    confirmed: (ctx, { log }) => log('Order confirmed!')
  },
  on: {
    SUBMIT: (ctx, { set }) => set({ submittedAt: Date.now() })
  }
});

order.send('SUBMIT');
console.log(order.state); // 'pending'

Features:

• XState import/export (fromXState, toXState)
• Behavior helpers: set(), send(), log()
• Auto-timers for delayed transitions
• Visual debugging with FSM Studio

Framework Adapters

Official bindings with auto-cleanup on unmount:

| Package | Framework | Docs | |---------|-----------|------| | @quazardous/quarkernel-vue | Vue 3 | README | | @quazardous/quarkernel-react | React 18+ | README | | @quazardous/quarkernel-svelte | Svelte 5 | README |

# Vue
npm install @quazardous/quarkernel @quazardous/quarkernel-vue

# React
npm install @quazardous/quarkernel @quazardous/quarkernel-react

# Svelte
npm install @quazardous/quarkernel @quazardous/quarkernel-svelte

Documentation

Guides:

• Getting Started - Installation, first event, basic usage
• API Reference - Complete API documentation
• Advanced Patterns - Multi-machine, composition, sagas
• Async Integration - QK + FSM + Promises synergies
• Migration v1 to v2 - Upgrade guide

Packages:

• Core package - Main QuarKernel library

Resources:

• Benchmarks - Performance comparisons
• Demos - Live examples

Use Cases

Request pipeline - Auth, validate, transform, respond in guaranteed order

Game events - Combo detection with composite events

Form wizards - Step dependencies with shared validation context

Order workflows - State machines for order lifecycle (draft → pending → confirmed → shipped)

Analytics - Wildcard listeners for all track:* events

Microservices - Event choreography with dependency graphs

UI flows - FSM-driven modals, wizards, and multi-step forms

License

MIT - Made by quazardous