@portel/photon-core 1.0.2 → 1.1.0

package/dist/elicit.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Elicit - Cross-platform user input for Photon
+ *
+ * Provides a unified API for requesting user input that works across:
+ * - Native OS dialogs (default - works standalone without photon runtime)
+ * - CLI readline (photon CLI overrides via globalThis.__photon_prompt__)
+ * - MCP elicitation (photon MCP overrides when client supports it)
+ *
+ * Design:
+ * - Photon files call the simple `prompt()` function (no imports needed)
+ * - Standalone: Uses native OS dialogs
+ * - Photon runtime: Overrides globalThis.__photon_prompt__ with appropriate handler
+ */
+export interface ElicitOptions {
+    /** The prompt/message to display to the user */
+    prompt: string;
+    /** Title for the dialog (used in GUI dialogs) */
+    title?: string;
+    /** Default value to pre-fill */
+    defaultValue?: string;
+    /** Type of input */
+    type?: 'text' | 'password' | 'confirm';
+    /** JSON schema for validation (used in MCP elicitation) */
+    schema?: object;
+    /** Timeout in milliseconds (0 = no timeout) */
+    timeout?: number;
+}
+export interface ElicitResult {
+    /** Whether the user provided input (vs cancelled) */
+    success: boolean;
+    /** The user's input value */
+    value?: string;
+    /** True if user confirmed (for confirm type) */
+    confirmed?: boolean;
+    /** Error message if failed */
+    error?: string;
+}
+/** Prompt handler type - simple string in, string out */
+export type PromptHandler = (message: string, defaultValue?: string) => Promise<string | null>;
+/** Full elicit handler type */
+export type ElicitHandler = (options: ElicitOptions) => Promise<ElicitResult>;
+declare global {
+    var __photon_prompt__: PromptHandler | undefined;
+    var __photon_elicit__: ElicitHandler | undefined;
+}
+/**
+ * Set the prompt handler (simple string-based)
+ * Runtimes use this to override with readline, MCP elicitation, etc.
+ */
+export declare function setPromptHandler(handler: PromptHandler | null): void;
+/**
+ * Set the full elicit handler (with options)
+ */
+export declare function setElicitHandler(handler: ElicitHandler | null): void;
+/**
+ * Simple prompt function - can be called directly from photon files
+ * No imports needed - uses global override or falls back to native dialog
+ *
+ * @example
+ * ```typescript
+ * // In a photon file - works standalone or with photon runtime
+ * const code = await prompt('Enter the 6-digit code:');
+ * if (code) {
+ *   console.log('User entered:', code);
+ * }
+ * ```
+ */
+export declare function prompt(message: string, defaultValue?: string): Promise<string | null>;
+/**
+ * Confirm dialog - returns true/false
+ */
+export declare function confirm(message: string): Promise<boolean>;
+/**
+ * Full elicit with options
+ */
+export declare function elicit(options: ElicitOptions): Promise<ElicitResult>;
+/**
+ * Get the current prompt handler
+ */
+export declare function getPromptHandler(): PromptHandler | undefined;
+/**
+ * Get the current elicit handler
+ */
+export declare function getElicitHandler(): ElicitHandler | undefined;
+/**
+ * Elicit using readline (for CLI/terminal)
+ */
+export declare function elicitReadline(options: ElicitOptions): Promise<ElicitResult>;
+/**
+ * Elicit using native OS dialog
+ */
+export declare function elicitNativeDialog(options: ElicitOptions): Promise<ElicitResult>;
+//# sourceMappingURL=elicit.d.ts.map

package/dist/elicit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elicit.d.ts","sourceRoot":"","sources":["../src/elicit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IACvC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,yDAAyD;AACzD,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAE/F,+BAA+B;AAC/B,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAG9E,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,iBAAiB,EAAE,aAAa,GAAG,SAAS,CAAC;IACjD,IAAI,iBAAiB,EAAE,aAAa,GAAG,SAAS,CAAC;CAClD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAEpE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAEpE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAc3F;AAED;;GAEG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAe/D;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAa1E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA2ClF;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAqBtF"}

package/dist/elicit.js

@@ -0,0 +1,373 @@
+/**
+ * Elicit - Cross-platform user input for Photon
+ *
+ * Provides a unified API for requesting user input that works across:
+ * - Native OS dialogs (default - works standalone without photon runtime)
+ * - CLI readline (photon CLI overrides via globalThis.__photon_prompt__)
+ * - MCP elicitation (photon MCP overrides when client supports it)
+ *
+ * Design:
+ * - Photon files call the simple `prompt()` function (no imports needed)
+ * - Standalone: Uses native OS dialogs
+ * - Photon runtime: Overrides globalThis.__photon_prompt__ with appropriate handler
+ */
+import { exec } from 'child_process';
+import * as os from 'os';
+import * as readline from 'readline';
+/**
+ * Set the prompt handler (simple string-based)
+ * Runtimes use this to override with readline, MCP elicitation, etc.
+ */
+export function setPromptHandler(handler) {
+    globalThis.__photon_prompt__ = handler || undefined;
+}
+/**
+ * Set the full elicit handler (with options)
+ */
+export function setElicitHandler(handler) {
+    globalThis.__photon_elicit__ = handler || undefined;
+}
+/**
+ * Simple prompt function - can be called directly from photon files
+ * No imports needed - uses global override or falls back to native dialog
+ *
+ * @example
+ * ```typescript
+ * // In a photon file - works standalone or with photon runtime
+ * const code = await prompt('Enter the 6-digit code:');
+ * if (code) {
+ *   console.log('User entered:', code);
+ * }
+ * ```
+ */
+export async function prompt(message, defaultValue) {
+    // Check for runtime override
+    if (globalThis.__photon_prompt__) {
+        return globalThis.__photon_prompt__(message, defaultValue);
+    }
+    // Fall back to native dialog
+    const result = await elicitNativeDialog({
+        prompt: message,
+        defaultValue,
+        type: 'text',
+    });
+    return result.success ? (result.value ?? null) : null;
+}
+/**
+ * Confirm dialog - returns true/false
+ */
+export async function confirm(message) {
+    if (globalThis.__photon_elicit__) {
+        const result = await globalThis.__photon_elicit__({
+            prompt: message,
+            type: 'confirm',
+        });
+        return result.confirmed ?? false;
+    }
+    const result = await elicitNativeDialog({
+        prompt: message,
+        type: 'confirm',
+    });
+    return result.confirmed ?? false;
+}
+/**
+ * Full elicit with options
+ */
+export async function elicit(options) {
+    // Use custom handler if set
+    if (globalThis.__photon_elicit__) {
+        return globalThis.__photon_elicit__(options);
+    }
+    // Check if we're in a TTY (interactive terminal)
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+        return elicitReadline(options);
+    }
+    // Default to native OS dialog
+    return elicitNativeDialog(options);
+}
+/**
+ * Get the current prompt handler
+ */
+export function getPromptHandler() {
+    return globalThis.__photon_prompt__;
+}
+/**
+ * Get the current elicit handler
+ */
+export function getElicitHandler() {
+    return globalThis.__photon_elicit__;
+}
+/**
+ * Elicit using readline (for CLI/terminal)
+ */
+export async function elicitReadline(options) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        const prompt = options.defaultValue
+            ? `${options.prompt} [${options.defaultValue}]: `
+            : `${options.prompt}: `;
+        if (options.type === 'confirm') {
+            rl.question(`${options.prompt} (y/n): `, (answer) => {
+                rl.close();
+                const confirmed = answer.toLowerCase().startsWith('y');
+                resolve({
+                    success: true,
+                    confirmed,
+                    value: confirmed ? 'yes' : 'no',
+                });
+            });
+        }
+        else {
+            rl.question(prompt, (answer) => {
+                rl.close();
+                const value = answer || options.defaultValue || '';
+                resolve({
+                    success: true,
+                    value,
+                });
+            });
+        }
+        // Handle timeout
+        if (options.timeout && options.timeout > 0) {
+            setTimeout(() => {
+                rl.close();
+                resolve({
+                    success: false,
+                    error: 'Input timeout',
+                });
+            }, options.timeout);
+        }
+    });
+}
+/**
+ * Elicit using native OS dialog
+ */
+export async function elicitNativeDialog(options) {
+    const platform = os.platform();
+    try {
+        switch (platform) {
+            case 'darwin':
+                return elicitMacOS(options);
+            case 'win32':
+                return elicitWindows(options);
+            case 'linux':
+                return elicitLinux(options);
+            default:
+                // Fallback to readline for unsupported platforms
+                return elicitReadline(options);
+        }
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error.message,
+        };
+    }
+}
+/**
+ * macOS: Use osascript (AppleScript) for dialogs
+ */
+function elicitMacOS(options) {
+    return new Promise((resolve) => {
+        const title = options.title || 'Input Required';
+        const prompt = options.prompt;
+        const defaultValue = options.defaultValue || '';
+        const isPassword = options.type === 'password';
+        const isConfirm = options.type === 'confirm';
+        let script;
+        if (isConfirm) {
+            script = `
+        display dialog "${escapeAppleScript(prompt)}" ¬
+          with title "${escapeAppleScript(title)}" ¬
+          buttons {"Cancel", "No", "Yes"} ¬
+          default button "Yes"
+        set buttonPressed to button returned of result
+        return buttonPressed
+      `;
+        }
+        else if (isPassword) {
+            script = `
+        display dialog "${escapeAppleScript(prompt)}" ¬
+          with title "${escapeAppleScript(title)}" ¬
+          default answer "${escapeAppleScript(defaultValue)}" ¬
+          with hidden answer ¬
+          buttons {"Cancel", "OK"} ¬
+          default button "OK"
+        return text returned of result
+      `;
+        }
+        else {
+            script = `
+        display dialog "${escapeAppleScript(prompt)}" ¬
+          with title "${escapeAppleScript(title)}" ¬
+          default answer "${escapeAppleScript(defaultValue)}" ¬
+          buttons {"Cancel", "OK"} ¬
+          default button "OK"
+        return text returned of result
+      `;
+        }
+        exec(`osascript -e '${script.replace(/'/g, "'\"'\"'")}'`, (error, stdout, stderr) => {
+            if (error) {
+                // User cancelled
+                if (error.code === 1) {
+                    resolve({
+                        success: false,
+                        error: 'User cancelled',
+                    });
+                }
+                else {
+                    resolve({
+                        success: false,
+                        error: stderr || error.message,
+                    });
+                }
+                return;
+            }
+            const value = stdout.trim();
+            if (isConfirm) {
+                resolve({
+                    success: true,
+                    confirmed: value === 'Yes',
+                    value,
+                });
+            }
+            else {
+                resolve({
+                    success: true,
+                    value,
+                });
+            }
+        });
+    });
+}
+/**
+ * Windows: Use PowerShell for dialogs
+ */
+function elicitWindows(options) {
+    return new Promise((resolve) => {
+        const title = options.title || 'Input Required';
+        const prompt = options.prompt;
+        const defaultValue = options.defaultValue || '';
+        const isConfirm = options.type === 'confirm';
+        let script;
+        if (isConfirm) {
+            script = `
+        Add-Type -AssemblyName System.Windows.Forms
+        $result = [System.Windows.Forms.MessageBox]::Show('${escapePowerShell(prompt)}', '${escapePowerShell(title)}', 'YesNoCancel', 'Question')
+        Write-Output $result
+      `;
+        }
+        else {
+            script = `
+        Add-Type -AssemblyName Microsoft.VisualBasic
+        $result = [Microsoft.VisualBasic.Interaction]::InputBox('${escapePowerShell(prompt)}', '${escapePowerShell(title)}', '${escapePowerShell(defaultValue)}')
+        Write-Output $result
+      `;
+        }
+        exec(`powershell -Command "${script.replace(/"/g, '\\"')}"`, (error, stdout, stderr) => {
+            if (error) {
+                resolve({
+                    success: false,
+                    error: stderr || error.message,
+                });
+                return;
+            }
+            const value = stdout.trim();
+            if (isConfirm) {
+                if (value === 'Cancel') {
+                    resolve({
+                        success: false,
+                        error: 'User cancelled',
+                    });
+                }
+                else {
+                    resolve({
+                        success: true,
+                        confirmed: value === 'Yes',
+                        value,
+                    });
+                }
+            }
+            else {
+                if (value === '') {
+                    resolve({
+                        success: false,
+                        error: 'User cancelled',
+                    });
+                }
+                else {
+                    resolve({
+                        success: true,
+                        value,
+                    });
+                }
+            }
+        });
+    });
+}
+/**
+ * Linux: Use zenity or kdialog
+ */
+function elicitLinux(options) {
+    return new Promise((resolve) => {
+        const title = options.title || 'Input Required';
+        const prompt = options.prompt;
+        const defaultValue = options.defaultValue || '';
+        const isPassword = options.type === 'password';
+        const isConfirm = options.type === 'confirm';
+        // Try zenity first, then kdialog
+        let command;
+        if (isConfirm) {
+            command = `zenity --question --title="${escapeShell(title)}" --text="${escapeShell(prompt)}" 2>/dev/null || kdialog --yesno "${escapeShell(prompt)}" --title "${escapeShell(title)}" 2>/dev/null`;
+        }
+        else if (isPassword) {
+            command = `zenity --password --title="${escapeShell(title)}" 2>/dev/null || kdialog --password "${escapeShell(prompt)}" --title "${escapeShell(title)}" 2>/dev/null`;
+        }
+        else {
+            command = `zenity --entry --title="${escapeShell(title)}" --text="${escapeShell(prompt)}" --entry-text="${escapeShell(defaultValue)}" 2>/dev/null || kdialog --inputbox "${escapeShell(prompt)}" "${escapeShell(defaultValue)}" --title "${escapeShell(title)}" 2>/dev/null`;
+        }
+        exec(command, (error, stdout, stderr) => {
+            if (error) {
+                if (error.code === 1) {
+                    resolve({
+                        success: false,
+                        error: 'User cancelled',
+                    });
+                }
+                else {
+                    // Neither zenity nor kdialog available, fall back to readline
+                    elicitReadline(options).then(resolve);
+                }
+                return;
+            }
+            const value = stdout.trim();
+            if (isConfirm) {
+                resolve({
+                    success: true,
+                    confirmed: true,
+                    value: 'yes',
+                });
+            }
+            else {
+                resolve({
+                    success: true,
+                    value,
+                });
+            }
+        });
+    });
+}
+// Helper functions for escaping strings
+function escapeAppleScript(str) {
+    return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+function escapePowerShell(str) {
+    return str.replace(/'/g, "''");
+}
+function escapeShell(str) {
+    return str.replace(/"/g, '\\"').replace(/\$/g, '\\$').replace(/`/g, '\\`');
+}
+//# sourceMappingURL=elicit.js.map

package/dist/elicit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"elicit.js","sourceRoot":"","sources":["../src/elicit.ts"],"names":[],"mappings":"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"}

package/dist/generator.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Generator-based Tool Execution
+ *
+ * Enables photon tools to use generator functions with `yield` for:
+ * - User prompts (text, password, confirm, select)
+ * - Progress updates
+ * - Streaming responses
+ * - Multi-step wizards
+ *
+ * The runtime handles yields appropriately based on the protocol:
+ * - REST: Extract yields as optional parameters
+ * - WebSocket/MCP: Interactive prompts
+ * - CLI: readline prompts
+ * - Fallback: Native OS dialogs
+ *
+ * @example
+ * ```typescript
+ * async *connect(params: { ip: string }) {
+ *   await this.startConnection(params.ip);
+ *
+ *   const code: string = yield {
+ *     prompt: 'Enter the 6-digit code:',
+ *     type: 'text'
+ *   };
+ *
+ *   await this.sendCode(code);
+ *   return { success: true };
+ * }
+ * ```
+ */
+/**
+ * Text input prompt
+ */
+export interface PromptYield {
+    prompt: string;
+    type?: 'text' | 'password';
+    default?: string;
+    /** Unique identifier for this prompt (auto-generated if not provided) */
+    id?: string;
+    /** Validation pattern */
+    pattern?: string;
+    /** Whether this prompt is required */
+    required?: boolean;
+}
+/**
+ * Confirmation dialog
+ */
+export interface ConfirmYield {
+    confirm: string;
+    /** Mark as dangerous action (UI can show warning styling) */
+    dangerous?: boolean;
+    id?: string;
+}
+/**
+ * Selection from options
+ */
+export interface SelectYield {
+    select: string;
+    options: Array<string | {
+        value: string;
+        label: string;
+    }>;
+    /** Allow multiple selections */
+    multi?: boolean;
+    id?: string;
+}
+/**
+ * Progress update (for long-running operations)
+ */
+export interface ProgressYield {
+    progress: number;
+    status?: string;
+    /** Additional data to stream to client */
+    data?: any;
+}
+/**
+ * Stream data to client
+ */
+export interface StreamYield {
+    stream: any;
+    /** Whether this is the final chunk */
+    final?: boolean;
+}
+/**
+ * Log/debug message
+ */
+export interface LogYield {
+    log: string;
+    level?: 'debug' | 'info' | 'warn' | 'error';
+}
+/**
+ * All possible yield types
+ */
+export type PhotonYield = PromptYield | ConfirmYield | SelectYield | ProgressYield | StreamYield | LogYield;
+/**
+ * Check if a yield requires user input
+ */
+export declare function isInputYield(y: PhotonYield): y is PromptYield | ConfirmYield | SelectYield;
+/**
+ * Check if a yield is a progress update
+ */
+export declare function isProgressYield(y: PhotonYield): y is ProgressYield;
+/**
+ * Check if a yield is streaming data
+ */
+export declare function isStreamYield(y: PhotonYield): y is StreamYield;
+/**
+ * Check if a yield is a log message
+ */
+export declare function isLogYield(y: PhotonYield): y is LogYield;
+/**
+ * Function that provides input for a yield
+ * Runtimes implement this based on their protocol
+ */
+export type InputProvider = (yielded: PhotonYield) => Promise<any>;
+/**
+ * Handler for non-input yields (progress, stream, log)
+ */
+export type OutputHandler = (yielded: PhotonYield) => void | Promise<void>;
+/**
+ * Configuration for generator execution
+ */
+export interface GeneratorExecutorConfig {
+    /** Provides input for prompt/confirm/select yields */
+    inputProvider: InputProvider;
+    /** Handles progress/stream/log yields */
+    outputHandler?: OutputHandler;
+    /** Pre-provided inputs (for REST APIs) */
+    preProvidedInputs?: Record<string, any>;
+    /** Timeout for waiting for input (ms) */
+    inputTimeout?: number;
+}
+/**
+ * Execute a generator-based tool
+ *
+ * @param generator - The async generator to execute
+ * @param config - Configuration for handling yields
+ * @returns The final return value of the generator
+ *
+ * @example
+ * ```typescript
+ * const result = await executeGenerator(tool.connect({ ip: '192.168.1.1' }), {
+ *   inputProvider: async (y) => {
+ *     if ('prompt' in y) return await readline(y.prompt);
+ *     if ('confirm' in y) return await confirm(y.confirm);
+ *   },
+ *   outputHandler: (y) => {
+ *     if ('progress' in y) console.log(`Progress: ${y.progress}%`);
+ *   }
+ * });
+ * ```
+ */
+export declare function executeGenerator<T>(generator: AsyncGenerator<PhotonYield, T, any>, config: GeneratorExecutorConfig): Promise<T>;
+/**
+ * Check if a function is an async generator function
+ */
+export declare function isAsyncGeneratorFunction(fn: any): fn is (...args: any[]) => AsyncGenerator;
+/**
+ * Check if a value is an async generator (already invoked)
+ */
+export declare function isAsyncGenerator(obj: any): obj is AsyncGenerator;
+/**
+ * Information about a yield point extracted from a generator
+ */
+export interface ExtractedYield {
+    id: string;
+    type: 'prompt' | 'confirm' | 'select';
+    prompt?: string;
+    options?: Array<string | {
+        value: string;
+        label: string;
+    }>;
+    default?: string;
+    required?: boolean;
+    pattern?: string;
+    dangerous?: boolean;
+    multi?: boolean;
+}
+/**
+ * Extract yield information by running generator with mock provider
+ * This is used for REST API schema generation
+ *
+ * Note: This only extracts yields that are reachable with default/empty inputs
+ * Complex conditional yields may not be extracted
+ */
+export declare function extractYields(generatorFn: (...args: any[]) => AsyncGenerator<PhotonYield, any, any>, mockParams?: any): Promise<ExtractedYield[]>;
+/**
+ * Create an input provider from pre-provided values
+ * Throws if a required value is missing
+ */
+export declare function createPrefilledProvider(inputs: Record<string, any>): InputProvider;
+/**
+ * Error thrown when input is needed but not available
+ * Runtimes can catch this to return appropriate responses
+ */
+export declare class NeedsInputError extends Error {
+    readonly yielded: PhotonYield;
+    constructor(yielded: PhotonYield);
+}
+/**
+ * Wrap a regular async function to behave like a generator
+ * Useful for uniform handling in runtimes
+ */
+export declare function wrapAsGenerator<T>(asyncFn: () => Promise<T>): AsyncGenerator<never, T, unknown>;
+//# sourceMappingURL=generator.d.ts.map