hakojs/dist/types/vm/value-factory.d.ts

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

import type { Container } from "../host/container";
import type { VMContext } from "./context";
import { VMValue } from "./value";
/**
 * Factory class for creating JavaScript values in the PrimJS virtual machine.
 *
 * ValueFactory converts JavaScript values from the host environment into
 * their corresponding representations in the PrimJS VM. It handles all primitive
 * and complex types, with special handling for objects, functions, and errors.
 *
 * @implements {Disposable} - Implements the Disposable interface for resource cleanup
 */
export declare class ValueFactory implements Disposable {
    /**
     * The VM context in which values will be created
     * @private
     */
    private context;
    /**
     * Reference to the container with core services
     * @private
     */
    private container;
    /**
     * Creates a new ValueFactory instance.
     *
     * @param context - The VM context in which values will be created
     * @param container - The service container providing access to PrimJS services
     */
    constructor(context: VMContext, container: Container);
    /**
     * Gets the VM context associated with this factory.
     *
     * @returns The VM context
     */
    getContext(): VMContext;
    /**
     * Converts a JavaScript value from the host environment to a VM value.
     *
     * This method handles all primitive types (undefined, null, boolean, number, string, bigint),
     * as well as complex types (arrays, objects, dates, errors, etc.). It recursively converts
     * nested values in objects and arrays.
     *
     * @param value - The JavaScript value to convert
     * @param options - Additional options for value creation:
     *                  - name: For functions, the function name (required)
     *                  - isGlobal: For symbols, whether it's a global symbol
     *                  - proto: For objects, an optional prototype object
     * @returns A VM value representation of the input
     * @throws Error if the value type is unsupported or conversion fails
     */
    fromNativeValue(value: unknown, options?: Record<string, unknown>): VMValue;
    /**
     * Creates a VM Error object from a JavaScript Error.
     *
     * @param value - The JavaScript Error object
     * @returns A VM Error object with name, message, stack, and cause properties
     * @private
     */
    private createError;
    /**
     * Creates a VM function from a host callback function.
     *
     * @param callback - The host callback function to wrap
     * @param options - Options object with required 'name' property
     * @returns A VM function value
     * @throws Error if function name is not provided
     * @private
     */
    private createFunction;
    /**
     * Creates a VM undefined value.
     *
     * @returns A VM undefined value
     * @private
     */
    private createUndefined;
    /**
     * Creates a VM null value.
     *
     * @returns A VM null value
     * @private
     */
    private createNull;
    /**
     * Creates a VM boolean value.
     *
     * @param value - The JavaScript boolean value
     * @returns A VM boolean value
     * @private
     */
    private createBoolean;
    /**
     * Creates a VM number value.
     *
     * @param value - The JavaScript number value
     * @returns A VM number value
     * @private
     */
    private createNumber;
    /**
     * Creates a VM string value.
     *
     * @param value - The JavaScript string value
     * @returns A VM string value
     * @private
     */
    private createString;
    /**
     * Creates a VM BigInt value.
     *
     * @param value - The JavaScript BigInt value
     * @returns A VM BigInt value
     * @throws HakoError if BigInt support is not enabled in this build
     * @private
     */
    private createBigInt;
    /**
     * Creates a VM Symbol value.
     *
     * @param value - The JavaScript Symbol value
     * @param options - Options object with optional 'isGlobal' property
     * @returns A VM Symbol value
     * @private
     */
    private createSymbol;
    /**
     * Creates a VM Array value and populates it with converted elements.
     *
     * @param value - The JavaScript array
     * @returns A VM Array value
     * @private
     */
    private createArray;
    /**
     * Creates a VM Date value.
     *
     * @param value - The JavaScript Date object
     * @returns A VM Date value
     * @throws Error if Date creation fails
     * @private
     */
    private createDate;
    /**
     * Creates a VM ArrayBuffer value.
     *
     * @param value - The JavaScript ArrayBuffer or view (TypedArray, DataView)
     * @returns A VM ArrayBuffer value
     * @private
     */
    private createArrayBuffer;
    /**
     * Creates a VM Object value with properties from a JavaScript object.
     *
     * @param value - The JavaScript object
     * @param options - Options object with optional 'proto' property specifying a prototype
     * @returns A VM Object value
     * @throws Error if circular references are detected or object creation fails
     * @private
     */
    private createObject;
    /**
     * Gets the global object from the VM context.
     *
     * @returns The VM global object
     */
    getGlobalObject(): VMValue;
    /**
     * Disposes of all resources.
     *
     * Since caching has been removed, this method is now a no-op
     * but is kept for interface compatibility.
     */
    dispose(): void;
    /**
     * Implements the Symbol.dispose method for the Disposable interface.
     *
     * This allows the value factory to be used with the using statement
     * in environments that support the Disposable pattern.
     */
    [Symbol.dispose](): void;
}
//# sourceMappingURL=value-factory.d.ts.map