@quazardous/quarkernel 2.2.5 → 2.3.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { C as ContextMerger } from './index-BDf1xZi6.cjs';
-export { D as CircularDependencyError, b as Composition, E as CompositionEventName, q as CompositionFactory, f as CompositionOptions, e as ConflictInfo, s as ContextMergerFunction, h as EventData, u as EventDataType, i as EventMap, g as EventName, t as EventNames, p as EventStack, r as IComposition, j as IKernel, I as IKernelEvent, k as IListenerContext, a as Kernel, K as KernelEvent, o as KernelOptions, L as ListenerContext, n as ListenerEntry, l as ListenerFunction, m as ListenerOptions, F as MaxListenersExceededError, M as MissingDependencyError, P as PredicateFunction, U as UnbindFunction, d as createComposition, c as createKernel, H as defineMachine, y as isContextMerger, z as isContextMergerFunction, v as isEventName, B as isKernelEvent, w as isListenerFunction, A as isListenerOptions, x as isPredicateFunction, G as useMachine } from './index-BDf1xZi6.cjs';
-export { A as ActionFunction, k as AfterDef, h as BehaviorFn, i as BehaviorHelpers, B as BehaviorMachine, j as BuiltInHelpers, C as CreateMachineConfig, F as FSMEventData, G as GuardFunction, a as Machine, M as MachineConfig, b as MachineSnapshot, d as SendOptions, g as StateConfig, e as StateName, S as StateNode, T as TransitionDef, f as TransitionEvent, c as createMachine } from './create-machine-CYsscHPX.cjs';
+import { C as ContextMerger } from './index-KSnUuM2s.cjs';
+export { D as CircularDependencyError, b as Composition, E as CompositionEventName, q as CompositionFactory, f as CompositionOptions, e as ConflictInfo, s as ContextMergerFunction, h as EventData, u as EventDataType, i as EventMap, g as EventName, t as EventNames, p as EventStack, r as IComposition, j as IKernel, I as IKernelEvent, k as IListenerContext, a as Kernel, K as KernelEvent, o as KernelOptions, L as ListenerContext, n as ListenerEntry, l as ListenerFunction, m as ListenerOptions, F as MaxListenersExceededError, M as MissingDependencyError, P as PredicateFunction, U as UnbindFunction, d as createComposition, c as createKernel, H as defineMachine, y as isContextMerger, z as isContextMergerFunction, v as isEventName, B as isKernelEvent, w as isListenerFunction, A as isListenerOptions, x as isPredicateFunction, G as useMachine } from './index-KSnUuM2s.cjs';
+export { A as ActionFunction, k as AfterDef, h as BehaviorFn, i as BehaviorHelpers, B as BehaviorMachine, j as BuiltInHelpers, C as CreateMachineConfig, F as FSMEventData, G as GuardFunction, a as Machine, M as MachineConfig, b as MachineSnapshot, d as SendOptions, g as StateConfig, e as StateName, S as StateNode, T as TransitionDef, f as TransitionEvent, c as createMachine } from './create-machine-SGkCnU0g.cjs';
 export { ImportOptions, XStateConfigWithActions, XStateMachineConfig, formatStateCentricCode, fromXState, toXStateFormat } from './xstate.cjs';
 
 /**

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { C as ContextMerger } from './index-BPMXiW32.js';
-export { D as CircularDependencyError, b as Composition, E as CompositionEventName, q as CompositionFactory, f as CompositionOptions, e as ConflictInfo, s as ContextMergerFunction, h as EventData, u as EventDataType, i as EventMap, g as EventName, t as EventNames, p as EventStack, r as IComposition, j as IKernel, I as IKernelEvent, k as IListenerContext, a as Kernel, K as KernelEvent, o as KernelOptions, L as ListenerContext, n as ListenerEntry, l as ListenerFunction, m as ListenerOptions, F as MaxListenersExceededError, M as MissingDependencyError, P as PredicateFunction, U as UnbindFunction, d as createComposition, c as createKernel, H as defineMachine, y as isContextMerger, z as isContextMergerFunction, v as isEventName, B as isKernelEvent, w as isListenerFunction, A as isListenerOptions, x as isPredicateFunction, G as useMachine } from './index-BPMXiW32.js';
-export { A as ActionFunction, k as AfterDef, h as BehaviorFn, i as BehaviorHelpers, B as BehaviorMachine, j as BuiltInHelpers, C as CreateMachineConfig, F as FSMEventData, G as GuardFunction, a as Machine, M as MachineConfig, b as MachineSnapshot, d as SendOptions, g as StateConfig, e as StateName, S as StateNode, T as TransitionDef, f as TransitionEvent, c as createMachine } from './create-machine-CYsscHPX.js';
+import { C as ContextMerger } from './index-0UbjHkkt.js';
+export { D as CircularDependencyError, b as Composition, E as CompositionEventName, q as CompositionFactory, f as CompositionOptions, e as ConflictInfo, s as ContextMergerFunction, h as EventData, u as EventDataType, i as EventMap, g as EventName, t as EventNames, p as EventStack, r as IComposition, j as IKernel, I as IKernelEvent, k as IListenerContext, a as Kernel, K as KernelEvent, o as KernelOptions, L as ListenerContext, n as ListenerEntry, l as ListenerFunction, m as ListenerOptions, F as MaxListenersExceededError, M as MissingDependencyError, P as PredicateFunction, U as UnbindFunction, d as createComposition, c as createKernel, H as defineMachine, y as isContextMerger, z as isContextMergerFunction, v as isEventName, B as isKernelEvent, w as isListenerFunction, A as isListenerOptions, x as isPredicateFunction, G as useMachine } from './index-0UbjHkkt.js';
+export { A as ActionFunction, k as AfterDef, h as BehaviorFn, i as BehaviorHelpers, B as BehaviorMachine, j as BuiltInHelpers, C as CreateMachineConfig, F as FSMEventData, G as GuardFunction, a as Machine, M as MachineConfig, b as MachineSnapshot, d as SendOptions, g as StateConfig, e as StateName, S as StateNode, T as TransitionDef, f as TransitionEvent, c as createMachine } from './create-machine-SGkCnU0g.js';
 export { ImportOptions, XStateConfigWithActions, XStateMachineConfig, formatStateCentricCode, fromXState, toXStateFormat } from './xstate.js';
 
 /**

package/dist/index.js

@@ -502,6 +502,39 @@ var Composition = class {
   onComposed(listener, options) {
     return this.kernel.on(COMPOSED_EVENT, listener, options);
   }
+  /**
+   * Wait for the next composition completion as a Promise
+   *
+   * @param options - Optional timeout configuration
+   * @returns Promise resolving with composed event data
+   *
+   * @example
+   * ```typescript
+   * // .then() receives: { sources, contexts, merged }
+   * const result = await composition.once();
+   * console.log(result.data.merged); // merged context from all sources
+   * console.log(result.data.sources); // ['event1', 'event2']
+   *
+   * // With timeout
+   * const result = await composition.once({ timeout: 5000 });
+   * ```
+   */
+  once(options) {
+    return new Promise((resolve, reject) => {
+      let timeoutId;
+      const listener = (event) => {
+        if (timeoutId) clearTimeout(timeoutId);
+        resolve(event);
+      };
+      const unbind = this.kernel.on(COMPOSED_EVENT, listener, { once: true });
+      if (options?.timeout) {
+        timeoutId = setTimeout(() => {
+          unbind();
+          reject(new Error(`composition.once() timed out after ${options.timeout}ms`));
+        }, options.timeout);
+      }
+    });
+  }
   /**
    * Remove a listener for composed events
    */
@@ -756,6 +789,42 @@ var Kernel = class _Kernel {
     }
     return () => this.off(event, listener);
   }
+  /**
+   * Wait for an event once (Promise-based)
+   *
+   * For callback style, use: `qk.on(event, listener, { once: true })`
+   *
+   * @param eventName - Event to wait for
+   * @param options - Optional timeout in ms
+   * @returns Promise resolving with the event
+   *
+   * @example
+   * ```typescript
+   * // .then() receives: IKernelEvent { name, data, context, timestamp }
+   * const event = await qk.once('user:loaded');
+   * console.log(event.data);    // event payload
+   * console.log(event.context); // shared context
+   *
+   * // With timeout (rejects if event doesn't fire)
+   * const event = await qk.once('user:loaded', { timeout: 5000 });
+   * ```
+   */
+  once(eventName, options) {
+    return new Promise((resolve, reject) => {
+      let timeoutId;
+      const listener = (event) => {
+        if (timeoutId) clearTimeout(timeoutId);
+        resolve(event);
+      };
+      const unbind = this.on(eventName, listener, { once: true });
+      if (options?.timeout) {
+        timeoutId = setTimeout(() => {
+          unbind();
+          reject(new Error(`once('${String(eventName)}') timed out after ${options.timeout}ms`));
+        }, options.timeout);
+      }
+    });
+  }
   /**
    * Remove an event listener
    * If no listener provided, removes all listeners for the event
@@ -1412,6 +1481,37 @@ function useMachine(kernel, config) {
         history = [...snapshot2.history];
       }
     },
+    waitFor(targetState, options) {
+      if (currentState === targetState) {
+        return Promise.resolve({
+          state: currentState,
+          context: structuredClone(context)
+        });
+      }
+      return new Promise((resolve, reject) => {
+        let timeoutId;
+        const unbind = kernel.on(
+          `${prefix}:enter:${targetState}`,
+          (event) => {
+            if (timeoutId) clearTimeout(timeoutId);
+            unbind();
+            resolve({
+              state: targetState,
+              from: event.data?.from,
+              event: event.data?.event,
+              context: structuredClone(context)
+            });
+          }
+        );
+        cleanupFns.push(unbind);
+        if (options?.timeout) {
+          timeoutId = setTimeout(() => {
+            unbind();
+            reject(new Error(`waitFor('${targetState}') timed out after ${options.timeout}ms`));
+          }, options.timeout);
+        }
+      });
+    },
     destroy() {
       for (const cleanup of cleanupFns) {
         cleanup();