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

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

import { type JSType, type JSValuePointer, type PromiseState, type PropertyEnumFlags, type TypedArrayType, type ValueLifecycle } from "../etc/types";
import { type NativeBox } from "../mem/lifetime";
import type { VMContext } from "./context";
/**
 * Represents a JavaScript value within the PrimJS virtual machine.
 *
 * VMValue provides a wrapper around JavaScript values in the WebAssembly VM,
 * allowing safe operations on these values from the host environment.
 * It handles resource management, type conversion, property access, and equality
 * comparisons while maintaining proper memory safety.
 *
 * @implements {Disposable} - Implements the Disposable interface for resource cleanup
 */
export declare class VMValue implements Disposable {
    /**
     * The VM context this value belongs to
     * @private
     */
    private context;
    /**
     * WebAssembly pointer to the underlying JavaScript value
     * @private
     */
    private handle;
    /**
     * Lifecycle mode of this value (owned, borrowed, or temporary)
     * @private
     */
    private lifecycle;
    /**
     * Creates a new VMValue instance.
     *
     * @param context - The VM context this value belongs to
     * @param handle - WebAssembly pointer to the JavaScript value
     * @param lifecycle - Lifecycle mode of this value, defaults to Owned
     */
    constructor(context: VMContext, handle: JSValuePointer, lifecycle?: ValueLifecycle);
    /**
     * Creates a new VMValue from an existing handle.
     *
     * Factory method to create VMValue instances with a specific lifecycle mode.
     *
     * @param ctx - The VM context
     * @param handle - WebAssembly pointer to the JavaScript value
     * @param lifecycle - Lifecycle mode of the value
     * @returns A new VMValue instance
     */
    static fromHandle(ctx: VMContext, handle: JSValuePointer, lifecycle: ValueLifecycle): VMValue;
    /**
     * Gets the internal WebAssembly pointer to the JavaScript value.
     *
     * @returns The JavaScript value pointer
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    getHandle(): JSValuePointer;
    /**
     * Checks if this value is still alive (not disposed).
     *
     * @returns True if the value is still valid, false if it has been disposed
     */
    get alive(): boolean;
    /**
     * Gets the WebAssembly pointer to the context this value belongs to.
     *
     * @returns The context pointer
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    getContextPointer(): number;
    /**
     * Consumes this value with a function and automatically disposes it afterward.
     *
     * This pattern ensures proper resource cleanup even if the consumer function throws.
     *
     * @template TReturn - The return type of the consumer function
     * @param consumer - Function that uses this value
     * @returns The result of the consumer function
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    consume<TReturn>(consumer: (value: VMValue) => TReturn): TReturn;
    /**
     * Creates a duplicate of this value.
     *
     * The duplicate is a separate value with its own lifecycle, referencing
     * the same JavaScript value in the VM.
     *
     * @returns A new owned VMValue that is a duplicate of this one
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    dup(): VMValue;
    /**
     * Creates a borrowed reference to this value.
     *
     * A borrowed reference shares the same handle but won't dispose it when
     * the borrowed reference itself is disposed.
     *
     * @returns A borrowed VMValue referencing the same JavaScript value
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    borrow(): VMValue;
    /**
     * Determines the JavaScript type of this value.
     *
     * @private
     * @returns The JavaScript type as a string
     */
    private getValueType;
    /**
     * Gets the JavaScript type of this value.
     *
     * @returns The JavaScript type as a string (e.g., "undefined", "number", "object")
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    get type(): JSType;
    /**
     * Checks if this value is undefined.
     *
     * @returns True if the value is undefined
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    isUndefined(): boolean;
    /**
     * Checks if this value is an Error object.
     *
     * @returns True if the value is an Error
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    isError(): boolean;
    /**
     * Checks if this value is an exception (represents an error state).
     *
     * @returns True if the value is an exception
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    isException(): boolean;
    /**
     * Checks if this value is null.
     *
     * @returns True if the value is null
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    isNull(): boolean;
    /**
     * Checks if this value is a boolean.
     *
     * @returns True if the value is a boolean
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    isBoolean(): boolean;
    /**
     * Checks if this value is a number.
     *
     * @returns True if the value is a number
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    isNumber(): boolean;
    /**
     * Checks if this value is a string.
     *
     * @returns True if the value is a string
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    isString(): boolean;
    /**
     * Checks if this value is a symbol.
     *
     * @returns True if the value is a symbol
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    isSymbol(): boolean;
    /**
     * Checks if this value is an object.
     *
     * @returns True if the value is an object
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    isObject(): boolean;
    /**
     * Checks if this value is an array.
     *
     * @returns True if the value is an array
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    isArray(): boolean;
    /**
     * Gets the type of typed array if this value is a typed array.
     *
     * @returns The specific type of typed array
     * @throws {TypeError} If the value is not a typed array
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    getTypedArrayType(): TypedArrayType;
    /**
     * Checks if this value is a typed array.
     *
     * @returns True if the value is a typed array
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    isTypedArray(): boolean;
    /**
     * Checks if this value is an ArrayBuffer.
     *
     * @returns True if the value is an ArrayBuffer
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    isArrayBuffer(): boolean;
    /**
     * Checks if this value is a function.
     *
     * @returns True if the value is a function
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    isFunction(): boolean;
    /**
     * Checks if this value is a Promise.
     *
     * @returns True if the value is a Promise
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    isPromise(): boolean;
    /**
     * Converts this value to a JavaScript number.
     *
     * @returns The numeric value
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    asNumber(): number;
    /**
     * Converts this value to a JavaScript boolean according to JavaScript truthiness rules.
     *
     * @returns The boolean value
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    asBoolean(): boolean;
    /**
     * Converts this value to a JavaScript string.
     *
     * @returns The string value
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    asString(): string;
    /**
     * Gets a property from this object.
     *
     * @param key - Property name, index, or VMValue key
     * @returns The property value
     * @throws Error if property access fails
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    getProperty(key: string | number | VMValue): VMValue;
    /**
     * Sets a property on this object.
     *
     * @param key - Property name, index, or VMValue key
     * @param value - Value to set (can be a JavaScript value or VMValue)
     * @returns True if the property was set successfully
     * @throws Error if property setting fails
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    setProperty(key: string | number | VMValue, value: unknown): boolean;
    /**
     * Defines a property with a property descriptor on this object.
     *
     * @param key - Property name or VMValue key
     * @param descriptor - Property descriptor with value, getter/setter, and attributes
     * @returns True if the property was defined successfully
     * @throws Error if property definition fails
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    defineProperty(key: string | VMValue, descriptor: PropertyDescriptor): boolean;
    /**
     * Checks if this value is a global symbol.
     *
     * @returns True if the value is a global symbol
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    isGlobalSymbol(): boolean;
    /**
     * Gets all own property names of this object.
     *
     * Returns a generator that yields each property name as a VMValue.
     *
     * @param flags - Flags to control which properties to include
     * @returns A generator yielding property name VMValues
     * @throws Error if property enumeration fails
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    getOwnPropertyNames(flags?: PropertyEnumFlags): Generator<VMValue, void, unknown>;
    /**
     * Gets the promise state if this value is a promise.
     *
     * @returns The promise state (Pending, Fulfilled, or Rejected)
     * @throws Error if the value is not a promise
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    getPromiseState(): PromiseState | undefined;
    /**
     * Gets the promise result if this value is a fulfilled or rejected promise.
     *
     * @returns The promise result value, or undefined if the promise is pending
     * @throws TypeError if the value is not a promise
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    getPromiseResult(): VMValue | undefined;
    /**
     * Converts this value to a JSON string.
     *
     * @param indent - Number of spaces for indentation, 0 for no formatting
     * @returns JSON string representation
     * @throws Error if JSON conversion fails
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    stringify(indent?: number): string;
    /**
     * Gets the BigInt value if this is a BigInt.
     *
     * @returns The BigInt value
     * @throws HakoError if BigInt support is not enabled
     * @throws TypeError if the value is not a BigInt
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    getBigInt(): bigint;
    /**
     * Gets the length of this value if it's an array.
     *
     * @returns The array length
     * @throws Error if the value is not an array
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    getLength(): number;
    /**
     * Converts this VM value to a native JavaScript value.
     *
     * Handles all JavaScript types including objects and arrays (recursively).
     * Returns a NativeBox that contains the value and implements the Disposable interface.
     *
     * @template TValue - The expected type of the native value
     * @returns A NativeBox containing the native value
     * @throws Error if conversion fails
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    toNativeValue<TValue = unknown>(): NativeBox<TValue>;
    /**
     * Extracts the data from a Uint8Array typed array.
     *
     * Copies the data from the VM typed array to a new host Uint8Array.
     *
     * @returns A Uint8Array containing the copied data
     * @throws TypeError if the value is not a Uint8Array
     * @throws Error if array copying fails
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    copyTypedArray(): Uint8Array;
    /**
     * Extracts the data from an ArrayBuffer.
     *
     * Copies the data from the VM ArrayBuffer to a new host ArrayBuffer.
     *
     * @returns An ArrayBuffer containing the copied data
     * @throws TypeError if the value is not an ArrayBuffer
     * @throws Error if buffer copying fails
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    copyArrayBuffer(): ArrayBuffer;
    /**
     * Disposes this value, freeing any associated resources.
     *
     * If this is an owned value, its handle will be freed. Borrowed values
     * will not have their handles freed.
     */
    dispose(): void;
    /**
     * Implements Symbol.dispose for the Disposable interface.
     *
     * This allows VMValue to be used with `using` statements in
     * environments that support the Disposable pattern.
     */
    [Symbol.dispose](): void;
    /**
     * Compares two VMValues for equality.
     *
     * @param a - First VMValue to compare
     * @param b - Second VMValue to compare
     * @param ctx - Context pointer
     * @param compar - Comparison function from exports
     * @param equalityType - Type of equality comparison to perform
     * @returns True if the values are equal according to the specified comparison
     * @private
     */
    private static isEqual;
    /**
     * Gets the class ID of this value.
     *
     * This is useful for checking instance types using instanceof.
     *
     * @returns The class ID, or 0 if not a class instance
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    classId(): number;
    getOpaque(): number;
    setOpaque(opaque: number): void;
    freeOpaque(): void;
    /**
     * Checks if this value is an instance of another value (class).
     *
     * Equivalent to the JavaScript `instanceof` operator.
     *
     * @param other - The constructor or class to check against
     * @returns True if this value is an instance of the specified constructor
     * @throws Error if the check fails
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     */
    instanceof(other: VMValue): boolean;
    /**
     * Checks if this value is strictly equal to another value.
     *
     * Equivalent to the JavaScript `===` operator.
     * See [Equality comparisons and sameness](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness).
     *
     * @param other - The value to compare with
     * @returns True if the values are strictly equal
     */
    eq(other: VMValue): boolean;
    /**
     * Checks if this value is the same value as another (Object.is semantics).
     *
     * Equivalent to JavaScript's `Object.is()` function.
     * See [Equality comparisons and sameness](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness).
     *
     * @param other - The value to compare with
     * @returns True if the values are the same according to Object.is
     */
    sameValue(other: VMValue): boolean;
    /**
     * Checks if this value is the same as another using SameValueZero comparison.
     *
     * SameValueZero is like Object.is but treats +0 and -0 as equal.
     * This is the comparison used by methods like Array.prototype.includes().
     * See [Equality comparisons and sameness](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness).
     *
     * @param other - The value to compare with
     * @returns True if the values are the same according to SameValueZero
     */
    sameValueZero(other: VMValue): boolean;
    /**
     * Verifies that this value is still alive (not disposed).
     *
     * @throws {PrimJSUseAfterFree} If the value has been disposed
     * @private
     */
    private assertAlive;
}
//# sourceMappingURL=value.d.ts.map