hakojs/dist/types/helpers/iterator-helper.d.ts

A secure, embeddable JavaScript engine that runs untrusted code inside WebAssembly sandboxes with fine-grained permissions and resource limits

import type { VMContextResult } from "../etc/types";
import type { HakoRuntime } from "../host/runtime";
import type { VMContext } from "../vm/context";
import { VMValue } from "../vm/value";
/**
 * Proxies the iteration protocol from the host to a guest iterator.
 *
 * VMIterator bridges the gap between JavaScript iterators in the host environment
 * and iterators inside the VM context, allowing you to iterate over VM collections
 * (arrays, maps, sets, etc.) using standard JavaScript iteration patterns.
 *
 * The guest iterator must be a PrimJS object with a standard `next` method
 * that follows the JavaScript iteration protocol. The iterator also supports
 * optional `return` and `throw` methods for full protocol compliance.
 * See [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols).
 *
 * Resource Management:
 * - If calling any method of the iteration protocol throws an error,
 *   the iterator is disposed after returning the exception as the final value.
 * - When the iterator is done, the handle is disposed automatically.
 * - The caller is responsible for disposing each yielded value.
 * - The class implements Disposable, so it can be used with `using` statements.
 *
 * @example
 * ```typescript
 * // Example: Iterating over a Map in the VM
 * using result = context.evalCode(`
 *   const map = new Map();
 *   map.set("key1", "value1");
 *   map.set("key2", "value2");
 *   map;
 * `);
 * using map = result.unwrap();
 *
 * for (using entriesBox of context.getIterator(map).unwrap()) {
 *   using entriesHandle = entriesBox.unwrap();
 *   using keyHandle = entriesHandle.getProperty(0).toNativeValue();
 *   using valueHandle = entriesHandle.getProperty(1).toNativeValue();
 *
 *   console.log(keyHandle.value, valueHandle.value);
 *   // Process key-value pairs
 * }
 * ```
 *
 * @implements {Disposable} - Implements the Disposable interface for resource cleanup
 * @implements {IterableIterator<VMContextResult<VMValue>>} - Implements the IterableIterator interface
 */
export declare class VMIterator implements Disposable, IterableIterator<VMContextResult<VMValue>> {
    handle: VMValue;
    context: VMContext;
    /**
     * Reference to the runtime that owns this iterator
     */
    owner: HakoRuntime;
    /**
     * Cached reference to the iterator's 'next' method
     * @private
     */
    private _next;
    /**
     * Flag indicating if the iterator has completed
     * @private
     */
    private _isDone;
    /**
     * Creates a new VMIterator to proxy iteration for a VM object
     *
     * @param handle - The VM object that implements the iterator protocol
     * @param context - The VM context in which the iterator exists
     */
    constructor(handle: VMValue, context: VMContext);
    /**
     * Returns this iterator instance, making VMIterator both an Iterable and Iterator.
     *
     * This enables using VMIterator with for-of loops.
     *
     * @returns This iterator instance
     */
    [Symbol.iterator](): this;
    /**
     * Gets the next value in the iteration sequence.
     *
     * This method calls the 'next' method on the VM iterator and processes its result
     * to conform to the JavaScript iterator protocol in the host environment.
     *
     * @param value - Optional value to pass to the iterator's next method
     * @returns An iterator result object with the next value and done status
     */
    next(value?: VMValue): IteratorResult<VMContextResult<VMValue>, unknown>;
    /**
     * Properly terminates the iterator and returns a final value.
     *
     * If the VM iterator has a 'return' method, this calls that method.
     * This method is automatically called by for-of loops when breaking out
     * of the loop early, allowing for proper resource cleanup.
     *
     * @param value - Optional value to pass to the iterator's return method
     * @returns An iterator result object marking the iterator as done
     */
    return(value?: VMValue): IteratorResult<VMContextResult<VMValue>, unknown>;
    /**
     * Signals an error to the iterator and terminates iteration.
     *
     * If the VM iterator has a 'throw' method, this calls that method to propagate
     * an error into the iterator, which might trigger catch blocks inside generator
     * functions in the VM.
     *
     * @param e - Error or VMValue to throw into the iterator
     * @returns An iterator result object with the error result
     * @throws {TypeError} If the error is neither an Error nor a VMValue
     */
    throw(e?: unknown): IteratorResult<VMContextResult<VMValue>, unknown>;
    /**
     * Checks if the iterator is still alive and not disposed.
     *
     * @returns True if the iterator handle is still alive, false otherwise
     */
    get alive(): boolean;
    /**
     * Disposes of all resources associated with this iterator.
     *
     * This method is idempotent - calling it multiple times has no additional effect.
     * It ensures that all handles are properly disposed.
     */
    dispose(): void;
    /**
     * Implements the Symbol.dispose method for the Disposable interface.
     *
     * This allows the iterator to be used with the using statement
     * in environments that support the Disposable pattern.
     */
    [Symbol.dispose](): void;
    /**
     * Helper method to call an iterator protocol method and process its result.
     *
     * This handles calling 'next', 'return', or 'throw' on the VM iterator and
     * processes the result to conform to the JavaScript iterator protocol.
     *
     * @param method - The VM method to call (next, return, or throw)
     * @param input - Optional value to pass to the method
     * @returns An iterator result object
     * @private
     */
    private callIteratorMethod;
}
//# sourceMappingURL=iterator-helper.d.ts.map