@quazardous/quarkernel 2.2.5 → 2.3.0

package/dist/{create-machine-CYsscHPX.d.cts → create-machine-SGkCnU0g.d.cts}

@@ -113,8 +113,40 @@ interface Machine<TContext = any> {
     getContext(): TContext;
     /** Update context */
     setContext(updater: Partial<TContext> | ((ctx: TContext) => TContext)): void;
-    /** Send transition event */
+    /**
+     * Send transition event
+     *
+     * @returns Promise<boolean> - true if transition occurred, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const transitioned = await machine.send('SUBMIT');
+     * // After await, check machine.getState() for current state
+     * ```
+     */
     send(event: TransitionEvent, payload?: any, options?: SendOptions<TContext>): Promise<boolean>;
+    /**
+     * Wait until machine reaches a specific state
+     *
+     * @param state - Target state to wait for
+     * @param options - Optional timeout
+     * @returns Promise resolving when state is reached
+     *
+     * @example
+     * ```typescript
+     * // .then() receives: { state, from?, event?, context }
+     * await machine.waitFor('completed');
+     * await machine.waitFor('completed', { timeout: 5000 });
+     * ```
+     */
+    waitFor(state: StateName, options?: {
+        timeout?: number;
+    }): Promise<{
+        state: StateName;
+        from?: StateName;
+        event?: TransitionEvent;
+        context: TContext;
+    }>;
     /** Check if transition is valid from current state */
     can(event: TransitionEvent): boolean;
     /** Get available transitions from current state */

package/dist/{create-machine-CYsscHPX.d.ts → create-machine-SGkCnU0g.d.ts}

@@ -113,8 +113,40 @@ interface Machine<TContext = any> {
     getContext(): TContext;
     /** Update context */
     setContext(updater: Partial<TContext> | ((ctx: TContext) => TContext)): void;
-    /** Send transition event */
+    /**
+     * Send transition event
+     *
+     * @returns Promise<boolean> - true if transition occurred, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const transitioned = await machine.send('SUBMIT');
+     * // After await, check machine.getState() for current state
+     * ```
+     */
     send(event: TransitionEvent, payload?: any, options?: SendOptions<TContext>): Promise<boolean>;
+    /**
+     * Wait until machine reaches a specific state
+     *
+     * @param state - Target state to wait for
+     * @param options - Optional timeout
+     * @returns Promise resolving when state is reached
+     *
+     * @example
+     * ```typescript
+     * // .then() receives: { state, from?, event?, context }
+     * await machine.waitFor('completed');
+     * await machine.waitFor('completed', { timeout: 5000 });
+     * ```
+     */
+    waitFor(state: StateName, options?: {
+        timeout?: number;
+    }): Promise<{
+        state: StateName;
+        from?: StateName;
+        event?: TransitionEvent;
+        context: TContext;
+    }>;
     /** Check if transition is valid from current state */
     can(event: TransitionEvent): boolean;
     /** Get available transitions from current state */

package/dist/fsm.cjs

@@ -460,6 +460,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
    */
@@ -711,6 +744,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
@@ -1310,6 +1379,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();