@quazardous/quarkernel 1.0.12 → 2.2.3

package/README.md

@@ -1,74 +1,195 @@
 # QuarKernel
 
-Micro Custom Event Kernel.
+[![npm version](https://img.shields.io/npm/v/@quazardous/quarkernel.svg?style=flat-square)](https://www.npmjs.com/package/@quazardous/quarkernel)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@quazardous/quarkernel?style=flat-square)](https://bundlephobia.com/package/@quazardous/quarkernel)
+[![license](https://img.shields.io/npm/l/@quazardous/quarkernel.svg?style=flat-square)](https://github.com/quazardous/quarkernel/blob/main/LICENSE)
 
-## Features
+**Event orchestration with dependency ordering, shared context, and state machines.**
 
-Helps structuring your app with events.
+TypeScript-first. Zero dependencies. < 2KB gzipped.
 
-- Modern: ES6, Async() support with Promise
-- Dependency support: easily handle async resource dependencies
-- Composite event: handle complex logic with a common event pipe
-- Shared context: use event data to share variable
+[![Try QK Studio](https://img.shields.io/badge/Try_it_live-QK_Studio-blue?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCI+PHBvbHlnb24gcG9pbnRzPSI1IDMgMTkgMTIgNSAyMSA1IDMiPjwvcG9seWdvbj48L3N2Zz4=)](https://quazardous.github.io/quarkernel/qk-studio/)
+[![Try FSM Studio](https://img.shields.io/badge/Try_it_live-FSM_Studio-purple?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiPjxjaXJjbGUgY3g9IjYiIGN5PSIxMiIgcj0iMyIvPjxjaXJjbGUgY3g9IjE4IiBjeT0iMTIiIHI9IjMiLz48bGluZSB4MT0iOSIgeTE9IjEyIiB4Mj0iMTUiIHkyPSIxMiIvPjwvc3ZnPg==)](https://quazardous.github.io/quarkernel/fsm-studio/)
+
+---
+
+## Why QuarKernel?
+
+```typescript
+// 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
 
 ```bash
-npm i "@quazardous/quarkernel"
+npm install @quazardous/quarkernel
+```
+
+```html
+<!-- CDN -->
+<script src="https://unpkg.com/@quazardous/quarkernel@2/dist/index.umd.js"></script>
 ```
 
-## Basic usage
+---
 
-Define event listeners across your app modules with dependency support.  
-Share context between components.  
+## Quick Start
 
-```js
-import { QuarKernel, QuarKernelEvent as QKE } from '@quazardous/quarkernel';
+```typescript
+import { createKernel } from '@quazardous/quarkernel';
 
-// singleton
-const qk = new QuarKernel();
+const qk = createKernel();
 
-qk.addEventListener('my_event', (e) => {
-    // something
-    notNeeded();
+// 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' });
+```
+
+```typescript
+// 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!');
 });
+```
 
-// your module foo does some init stuff
-qk.addEventListener('my_event', async (e) => {
-    // something async
-    e.context.needed = await needed();
-}, 'foo');
-
-// somewhere else in your app your module bar is waiting after foo to set a specific context
-qk.addEventListener('my_event', (e) => {
-    // something after the async callback
-    needing(e.context.needed);
-}, 'bar', 'foo');
-
-// call everything
-qk.dispatchEvent(new QKE('my_event')).then((e) => {
-    // event my_event fully dispatched
-    happyEnd();
+```typescript
+// 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:
+
+```typescript
+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() })
+  }
 });
-// or await qk.dispatchEvent(new QKE('my_event'));
+
+order.send('SUBMIT');
+console.log(order.state); // 'pending'
 ```
 
-## Composite event
+**Features:**
+- XState import/export (`fromXState`, `toXState`)
+- Behavior helpers: `set()`, `send()`, `log()`
+- Auto-timers for delayed transitions
+- Visual debugging with [FSM Studio](https://quazardous.github.io/quarkernel/fsm-studio/)
 
-Composite event are auto dispatched when a specific list of events are dispatched.
+---
 
-ie. You set a composite event C on A+B. Your code dispatches A, then B. C is auto dispatched after B.
+## Framework Adapters
 
-```js
-...
-// init
-qk.addCompositeEvent(['A','B'], (stack) => new QKE('C'));
-...
-qk.dispatchEvent(new QKE('A'));
-...
-// this will auto dispatch C
-qk.dispatchEvent(new QKE('B')); 
+Official bindings with auto-cleanup on unmount:
 
+| Package | Framework | Docs |
+|---------|-----------|------|
+| `@quazardous/quarkernel-vue` | Vue 3 | [README](https://github.com/quazardous/quarkernel/blob/main/packages/vue/README.md) |
+| `@quazardous/quarkernel-react` | React 18+ | [README](https://github.com/quazardous/quarkernel/blob/main/packages/react/README.md) |
+| `@quazardous/quarkernel-svelte` | Svelte 5 | [README](https://github.com/quazardous/quarkernel/blob/main/packages/svelte/README.md) |
+
+```bash
+# 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](https://github.com/quazardous/quarkernel/blob/main/docs/getting-started.md) - Installation, first event, basic usage
+- [API Reference](https://github.com/quazardous/quarkernel/blob/main/docs/api-reference.md) - Complete API documentation
+- [Advanced Patterns](https://github.com/quazardous/quarkernel/blob/main/docs/advanced-qk.md) - Multi-machine, composition, sagas
+- [Async Integration](https://github.com/quazardous/quarkernel/blob/main/docs/async-patterns.md) - QK + FSM + Promises synergies
+- [Migration v1 to v2](https://github.com/quazardous/quarkernel/blob/main/docs/migration-v1-to-v2.md) - Upgrade guide
+
+**Packages:**
+- [Core package](https://github.com/quazardous/quarkernel/blob/main/packages/quarkernel/README.md) - Main QuarKernel library
+
+**Resources:**
+- [Benchmarks](https://github.com/quazardous/quarkernel/blob/main/benchmarks/README.md) - Performance comparisons
+- [Demos](https://github.com/quazardous/quarkernel/blob/main/demos/README.md) - 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](https://github.com/quazardous/quarkernel/blob/main/LICENSE) - Made by [quazardous](https://github.com/quazardous)

package/dist/create-machine-CYsscHPX.d.cts

@@ -0,0 +1,275 @@
+/**
+ * FSM Types for QuarKernel
+ *
+ * Flexible state machine layer built on quarkernel events.
+ * Prefixed events allow loose coupling and multi-machine orchestration.
+ */
+/**
+ * State name type
+ */
+type StateName = string;
+/**
+ * Transition event name type
+ */
+type TransitionEvent = string;
+/**
+ * Guard function - returns true to allow transition
+ */
+type GuardFunction<TContext = any> = (context: TContext, event: TransitionEvent, payload?: any) => boolean;
+/**
+ * Action function - side effect on transition
+ */
+type ActionFunction<TContext = any> = (context: TContext, event: TransitionEvent, payload?: any) => void | Promise<void>;
+/**
+ * Transition definition
+ */
+interface TransitionDef<TContext = any> {
+    /** Target state */
+    target: StateName;
+    /** Guard condition (optional) */
+    guard?: GuardFunction<TContext>;
+    /** Actions to run on transition (optional) */
+    actions?: ActionFunction<TContext> | ActionFunction<TContext>[];
+}
+/**
+ * Timer/after definition for auto-transitions
+ */
+interface AfterDef$1 {
+    /** Delay in milliseconds */
+    delay: number;
+    /** Event to send after delay */
+    send: string;
+}
+/**
+ * State node definition (state-centric format)
+ */
+interface StateNode<TContext = any> {
+    /** Transitions from this state: event -> target or TransitionDef */
+    on?: Record<TransitionEvent, StateName | TransitionDef<TContext>>;
+    /** Action on entering this state */
+    entry?: ActionFunction<TContext>;
+    /** Action on exiting this state */
+    exit?: ActionFunction<TContext>;
+    /** Auto-transition after delay: { delay: 3000, send: 'TIMER' } */
+    after?: AfterDef$1;
+}
+/**
+ * Machine configuration
+ */
+interface MachineConfig<TContext = any> {
+    /** Event prefix for this machine (e.g., 'order', 'player') */
+    prefix: string;
+    /** Initial state */
+    initial: StateName;
+    /** State definitions */
+    states: Record<StateName, StateNode<TContext>>;
+    /** Initial context (optional) */
+    context?: TContext;
+    /** Allow force transitions that bypass guards */
+    allowForce?: boolean;
+    /** Restore from snapshot (overrides initial/context) */
+    snapshot?: MachineSnapshot<TContext>;
+    /** Track transition history */
+    trackHistory?: boolean;
+    /** Max history entries (default: 100) */
+    maxHistory?: number;
+}
+/**
+ * Send options
+ */
+interface SendOptions<TContext = any> {
+    /** Force transition (bypass guards and undefined transitions) */
+    force?: boolean;
+    /** Target state for force transitions */
+    target?: StateName;
+    /** Inline guard (overrides state guard) */
+    guard?: GuardFunction<TContext>;
+    /** Fallback state if guard fails */
+    fallback?: StateName;
+}
+/**
+ * Serialized machine state (for persistence)
+ */
+interface MachineSnapshot<TContext = any> {
+    /** Current state */
+    state: StateName;
+    /** Machine context */
+    context: TContext;
+    /** Transition history (optional) */
+    history?: Array<{
+        from: StateName;
+        to: StateName;
+        event: TransitionEvent;
+        timestamp: number;
+    }>;
+}
+/**
+ * Machine instance returned by useMachine()
+ */
+interface Machine<TContext = any> {
+    /** Current state */
+    getState(): StateName;
+    /** Machine context */
+    getContext(): TContext;
+    /** Update context */
+    setContext(updater: Partial<TContext> | ((ctx: TContext) => TContext)): void;
+    /** Send transition event */
+    send(event: TransitionEvent, payload?: any, options?: SendOptions<TContext>): Promise<boolean>;
+    /** Check if transition is valid from current state */
+    can(event: TransitionEvent): boolean;
+    /** Get available transitions from current state */
+    transitions(): TransitionEvent[];
+    /** Machine prefix */
+    readonly prefix: string;
+    /** Serialize machine state to JSON */
+    toJSON(): MachineSnapshot<TContext>;
+    /** Restore machine state from snapshot */
+    restore(snapshot: MachineSnapshot<TContext>): void;
+    /** Cleanup listeners */
+    destroy(): void;
+}
+/**
+ * FSM event data emitted on kernel
+ */
+interface FSMEventData {
+    /** Machine prefix */
+    machine: string;
+    /** Current/new state */
+    state: StateName;
+    /** Previous state (for transition events) */
+    from?: StateName;
+    /** Target state (for transition events) */
+    to?: StateName;
+    /** Transition event name */
+    event?: TransitionEvent;
+    /** Event payload */
+    payload?: any;
+    /** Whether this was a forced transition */
+    forced?: boolean;
+}
+
+/**
+ * createMachine - High-level FSM factory
+ *
+ * Standalone state machine with declarative behaviors.
+ * Can work independently or connect to a kernel.
+ */
+
+/**
+ * Built-in helpers (always available)
+ */
+interface BuiltInHelpers<TContext = Record<string, unknown>> {
+    /** Merge into context */
+    set: (partial: Partial<TContext>) => void;
+    /** Trigger transition */
+    send: (event: string, payload?: unknown) => void;
+    /** Log message (default: console.log) */
+    log: (message: string) => void;
+}
+/**
+ * Behavior helpers passed to callbacks (built-ins + custom)
+ */
+type BehaviorHelpers<TContext = Record<string, unknown>, TCustom = Record<string, unknown>> = BuiltInHelpers<TContext> & TCustom;
+/**
+ * Behavior callback
+ */
+type BehaviorFn<TContext = Record<string, unknown>> = (ctx: TContext, helpers: BehaviorHelpers<TContext>) => void | Promise<void>;
+/**
+ * Timer/after definition
+ */
+interface AfterDef {
+    /** Event to send */
+    send: string;
+    /** Delay in ms */
+    delay: number;
+}
+/**
+ * State-centric state definition
+ */
+interface StateConfig<TContext = Record<string, unknown>> {
+    /** Transitions: { EVENT: 'target' } or { EVENT: { target: 'x', cond: 'guard' } } */
+    on?: Record<string, string | {
+        target: string;
+        cond?: string;
+    }>;
+    /** Action on entering this state */
+    entry?: BehaviorFn<TContext>;
+    /** Action on exiting this state */
+    exit?: BehaviorFn<TContext>;
+    /** Auto-transition after delay: { delay: 3000, send: 'TIMER' } */
+    after?: AfterDef;
+}
+/**
+ * High-level machine config (state-centric)
+ */
+interface CreateMachineConfig<TContext = Record<string, unknown>, THelpers = Record<string, unknown>> {
+    /** Machine identifier */
+    id: string;
+    /** Initial state */
+    initial: string;
+    /** Initial context */
+    context?: TContext;
+    /** State definitions with entry/exit/after inline */
+    states: Record<string, StateConfig<TContext>>;
+    /** Global event handlers: { EVENT_NAME: (ctx, helpers) => ... } */
+    on?: Record<string, BehaviorFn<TContext>>;
+    /** Custom helpers merged with built-ins (set, send) */
+    helpers?: THelpers;
+}
+/**
+ * Extended machine interface with behaviors
+ */
+interface BehaviorMachine<TContext = Record<string, unknown>> extends Machine<TContext> {
+    /** Machine ID */
+    readonly id: string;
+    /** Current state (getter) */
+    readonly state: string;
+    /** Current context (getter) */
+    readonly context: TContext;
+}
+/**
+ * Create a standalone state machine with behaviors (state-centric)
+ *
+ * @example
+ * ```ts
+ * const order = createMachine({
+ *   id: 'order',
+ *   initial: 'draft',
+ *   context: { items: 0, total: 0 },
+ *
+ *   states: {
+ *     draft: {
+ *       on: { ADD_ITEM: 'draft', SUBMIT: 'pending' }
+ *     },
+ *     pending: {
+ *       entry: (ctx, { log }) => log('Order pending...'),
+ *       on: { APPROVE: 'confirmed', REJECT: 'draft' }
+ *     },
+ *     confirmed: {
+ *       entry: (ctx, { log }) => log(`Order confirmed: ${ctx.items} items`),
+ *       on: { SHIP: 'shipped' }
+ *     },
+ *     processing: {
+ *       after: { delay: 2000, send: 'COMPLETE' },
+ *       on: { COMPLETE: 'done' }
+ *     },
+ *     shipped: {},
+ *   },
+ *
+ *   // Global event handlers (optional)
+ *   on: {
+ *     ADD_ITEM: (ctx, { set }) => {
+ *       set({ items: ctx.items + 1, total: ctx.total + 29.99 });
+ *     },
+ *   },
+ * });
+ *
+ * order.send('ADD_ITEM');
+ * order.send('SUBMIT');
+ * console.log(order.state);   // 'pending'
+ * console.log(order.context); // { items: 1, total: 29.99 }
+ * ```
+ */
+declare function createMachine<TContext = Record<string, unknown>>(config: CreateMachineConfig<TContext>): BehaviorMachine<TContext>;
+
+export { type ActionFunction as A, type BehaviorMachine as B, type CreateMachineConfig as C, type FSMEventData as F, type GuardFunction as G, type MachineConfig as M, type StateNode as S, type TransitionDef as T, type Machine as a, type MachineSnapshot as b, createMachine as c, type SendOptions as d, type StateName as e, type TransitionEvent as f, type StateConfig as g, type BehaviorFn as h, type BehaviorHelpers as i, type BuiltInHelpers as j, type AfterDef as k, type AfterDef$1 as l };