@quazardous/quarkernel 1.0.11 → 2.2.2

package/README.md

@@ -1,74 +1,80 @@
-# QuarKernel
+# @quazardous/quarkernel
 
-Micro Custom Event Kernel.
+Event orchestration with dependency ordering and shared context.
 
-## Features
+[![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)
 
-Helps structuring your app with events.
+## Features
 
-- 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
+- **Dependency ordering** - Guarantee listener execution order
+- **Shared context** - Pass state between listeners
+- **Composite events** - React to event combinations
+- **Wildcards** - Pattern matching (`user:*`)
+- **TypeScript-first** - Full type safety
+- **Zero dependencies** - No runtime deps
+- **< 2KB gzipped**
 
-## Install
+## Installation
 
 ```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
+## Quick Start
 
-Define event listeners across your app modules with dependency support.  
-Share context between components.  
+```typescript
+import { createKernel } from '@quazardous/quarkernel';
 
-```js
-import { QuarKernel, QuarKernelEvent as QKE } from '@quazardous/quarkernel';
+const qk = createKernel();
 
-// singleton
-const qk = new QuarKernel();
+// Dependency ordering
+qk.on('checkout', async (e) => {
+  e.context.stock = await checkStock(e.data.items);
+}, { id: 'stock' });
 
-qk.addEventListener('my_event', (e) => {
-    // something
-    notNeeded();
-});
+qk.on('checkout', async (e) => {
+  // Runs AFTER stock check
+  await processPayment(e.data.card, e.context.stock);
+}, { after: ['stock'] });
 
-// 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();
-});
-// or await qk.dispatchEvent(new QKE('my_event'));
+await qk.emit('checkout', { items: ['sku-123'], card: 'tok_visa' });
 ```
 
-## Composite event
+## Composition
 
-Composite event are auto dispatched when a specific list of events are dispatched.
+React to multiple events:
 
-ie. You set a composite event C on A+B. Your code dispatches A, then B. C is auto dispatched after B.
+```typescript
+import { Composition } from '@quazardous/quarkernel';
 
-```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')); 
+const checkout = new Composition([
+  [qk, 'cart:ready'],
+  [qk, 'payment:confirmed']
+]);
 
+checkout.onComposed(() => {
+  console.log('Both events fired!');
+});
 ```
 
+## Framework Adapters
+
+- `@quazardous/quarkernel-vue` - Vue 3 plugin
+- `@quazardous/quarkernel-react` - React hooks
+- `@quazardous/quarkernel-svelte` - Svelte 5 context
+
+## Documentation
+
+- [Getting Started](../../docs/getting-started.md)
+- [API Reference](../../docs/api-reference.md)
+- [Migration v1 to v2](../../docs/migration-v1-to-v2.md)
+
+## License
 
+MIT

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 };

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

@@ -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 };