@quazardous/quarkernel 2.2.4 → 2.3.0

package/dist/{index-BDf1xZi6.d.cts → index-0UbjHkkt.d.ts}

@@ -1,4 +1,4 @@
-import { M as MachineConfig, a as Machine } from './create-machine-CYsscHPX.cjs';
+import { M as MachineConfig, a as Machine } from './create-machine-SGkCnU0g.js';
 
 /**
  * KernelEvent - Custom event implementation for QuarKernel
@@ -456,9 +456,20 @@ type ContextMergerFunction = (contexts: Record<string, any>) => any;
  */
 interface IKernel<Events extends EventMap = EventMap> {
     on<K extends keyof Events>(event: K | K[], listener: ListenerFunction<Events[K]>, options?: ListenerOptions): () => void;
-    once<K extends keyof Events>(event: K, listener: ListenerFunction<Events[K]>, options?: Omit<ListenerOptions, 'once'>): () => void;
-    once<K extends keyof Events>(event: K, predicate: PredicateFunction<Events[K]>, listener: ListenerFunction<Events[K]>, options?: Omit<ListenerOptions, 'once'>): () => void;
-    once<K extends keyof Events>(event: K): Promise<IKernelEvent<Events[K]>>;
+    /**
+     * Wait for an event once (Promise-based)
+     *
+     * For callback style, use: `on(event, listener, { once: true })`
+     *
+     * @example
+     * ```typescript
+     * const event = await qk.once('user:loaded');
+     * const event = await qk.once('user:loaded', { timeout: 5000 });
+     * ```
+     */
+    once<K extends keyof Events>(event: K, options?: {
+        timeout?: number;
+    }): Promise<IKernelEvent<Events[K]>>;
     off<K extends keyof Events>(event: K, listener?: ListenerFunction<Events[K]>): void;
     offAll(event?: keyof Events): void;
     emit<K extends keyof Events>(event: K, data?: Events[K]): Promise<void>;
@@ -617,6 +628,30 @@ declare class Composition<Events extends EventMap = EventMap> {
      * @returns Unbind function to remove the listener
      */
     onComposed(listener: ListenerFunction<Events[keyof Events]>, options?: ListenerOptions): () => void;
+    /**
+     * 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?: {
+        timeout?: number;
+    }): Promise<IKernelEvent<{
+        sources: EventName$1[];
+        contexts: Record<EventName$1, Record<string, any>>;
+        merged: Record<string, any>;
+    }>>;
     /**
      * Remove a listener for composed events
      */
@@ -748,6 +783,29 @@ declare class Kernel<Events extends EventMap = EventMap> implements ListenerCont
      * Returns an unbind function for cleanup
      */
     on<K extends keyof Events>(eventName: K, listener: ListenerFunction<Events[K]>, options?: ListenerOptions): () => void;
+    /**
+     * 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<K extends keyof Events>(eventName: K, options?: {
+        timeout?: number;
+    }): Promise<KernelEvent<Events[K]>>;
     /**
      * Remove an event listener
      * If no listener provided, removes all listeners for the event

package/dist/{index-BPMXiW32.d.ts → index-KSnUuM2s.d.cts}

@@ -1,4 +1,4 @@
-import { M as MachineConfig, a as Machine } from './create-machine-CYsscHPX.js';
+import { M as MachineConfig, a as Machine } from './create-machine-SGkCnU0g.cjs';
 
 /**
  * KernelEvent - Custom event implementation for QuarKernel
@@ -456,9 +456,20 @@ type ContextMergerFunction = (contexts: Record<string, any>) => any;
  */
 interface IKernel<Events extends EventMap = EventMap> {
     on<K extends keyof Events>(event: K | K[], listener: ListenerFunction<Events[K]>, options?: ListenerOptions): () => void;
-    once<K extends keyof Events>(event: K, listener: ListenerFunction<Events[K]>, options?: Omit<ListenerOptions, 'once'>): () => void;
-    once<K extends keyof Events>(event: K, predicate: PredicateFunction<Events[K]>, listener: ListenerFunction<Events[K]>, options?: Omit<ListenerOptions, 'once'>): () => void;
-    once<K extends keyof Events>(event: K): Promise<IKernelEvent<Events[K]>>;
+    /**
+     * Wait for an event once (Promise-based)
+     *
+     * For callback style, use: `on(event, listener, { once: true })`
+     *
+     * @example
+     * ```typescript
+     * const event = await qk.once('user:loaded');
+     * const event = await qk.once('user:loaded', { timeout: 5000 });
+     * ```
+     */
+    once<K extends keyof Events>(event: K, options?: {
+        timeout?: number;
+    }): Promise<IKernelEvent<Events[K]>>;
     off<K extends keyof Events>(event: K, listener?: ListenerFunction<Events[K]>): void;
     offAll(event?: keyof Events): void;
     emit<K extends keyof Events>(event: K, data?: Events[K]): Promise<void>;
@@ -617,6 +628,30 @@ declare class Composition<Events extends EventMap = EventMap> {
      * @returns Unbind function to remove the listener
      */
     onComposed(listener: ListenerFunction<Events[keyof Events]>, options?: ListenerOptions): () => void;
+    /**
+     * 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?: {
+        timeout?: number;
+    }): Promise<IKernelEvent<{
+        sources: EventName$1[];
+        contexts: Record<EventName$1, Record<string, any>>;
+        merged: Record<string, any>;
+    }>>;
     /**
      * Remove a listener for composed events
      */
@@ -748,6 +783,29 @@ declare class Kernel<Events extends EventMap = EventMap> implements ListenerCont
      * Returns an unbind function for cleanup
      */
     on<K extends keyof Events>(eventName: K, listener: ListenerFunction<Events[K]>, options?: ListenerOptions): () => void;
+    /**
+     * 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<K extends keyof Events>(eventName: K, options?: {
+        timeout?: number;
+    }): Promise<KernelEvent<Events[K]>>;
     /**
      * Remove an event listener
      * If no listener provided, removes all listeners for the event

package/dist/index.cjs

@@ -504,6 +504,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
    */
@@ -758,6 +791,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
@@ -1414,6 +1483,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();