@quazardous/quarkernel 2.2.4 → 2.3.0

package/dist/fsm.js

@@ -458,6 +458,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
    */
@@ -709,6 +742,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
@@ -1308,6 +1377,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();