JavaScriptEngine.java

/*
 * Copyright (c) 2002-2026 Gargoyle Software Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.htmlunit.javascript;

import static org.htmlunit.BrowserVersionFeatures.JS_ERROR_STACK_TRACE_LIMIT;
import static org.htmlunit.BrowserVersionFeatures.JS_WINDOW_INSTALL_TRIGGER_NULL;

import java.io.IOException;
import java.io.ObjectInputStream;
import java.lang.reflect.Member;
import java.lang.reflect.Method;
import java.net.URL;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Map.Entry;
import java.util.function.Consumer;

import org.apache.commons.lang3.ObjectUtils.Null;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.htmlunit.BrowserVersion;
import org.htmlunit.Page;
import org.htmlunit.ScriptException;
import org.htmlunit.WebAssert;
import org.htmlunit.WebClient;
import org.htmlunit.WebWindow;
import org.htmlunit.corejs.javascript.AbstractEcmaObjectOperations;
import org.htmlunit.corejs.javascript.BaseFunction;
import org.htmlunit.corejs.javascript.Callable;
import org.htmlunit.corejs.javascript.ClassDescriptor;
import org.htmlunit.corejs.javascript.Context;
import org.htmlunit.corejs.javascript.ContextAction;
import org.htmlunit.corejs.javascript.ContextFactory;
import org.htmlunit.corejs.javascript.EcmaError;
import org.htmlunit.corejs.javascript.Function;
import org.htmlunit.corejs.javascript.FunctionObject;
import org.htmlunit.corejs.javascript.JSFunction;
import org.htmlunit.corejs.javascript.JavaScriptException;
import org.htmlunit.corejs.javascript.NativeArray;
import org.htmlunit.corejs.javascript.NativeArrayIterator;
import org.htmlunit.corejs.javascript.NativeConsole;
import org.htmlunit.corejs.javascript.NativeObject;
import org.htmlunit.corejs.javascript.RhinoException;
import org.htmlunit.corejs.javascript.Script;
import org.htmlunit.corejs.javascript.ScriptRuntime;
import org.htmlunit.corejs.javascript.Scriptable;
import org.htmlunit.corejs.javascript.ScriptableObject;
import org.htmlunit.corejs.javascript.StackStyle;
import org.htmlunit.corejs.javascript.Symbol;
import org.htmlunit.corejs.javascript.SymbolKey;
import org.htmlunit.corejs.javascript.TopLevel;
import org.htmlunit.corejs.javascript.VarScope;
import org.htmlunit.corejs.javascript.WithScope;
import org.htmlunit.corejs.javascript.typedarrays.NativeArrayBuffer;
import org.htmlunit.corejs.javascript.typedarrays.NativeUint8Array;
import org.htmlunit.html.DomNode;
import org.htmlunit.html.HtmlElement;
import org.htmlunit.html.HtmlForm;
import org.htmlunit.html.HtmlPage;
import org.htmlunit.html.SubmittableElement;
import org.htmlunit.javascript.background.BackgroundJavaScriptFactory;
import org.htmlunit.javascript.background.JavaScriptExecutor;
import org.htmlunit.javascript.configuration.AbstractJavaScriptConfiguration;
import org.htmlunit.javascript.configuration.ClassConfiguration;
import org.htmlunit.javascript.configuration.ClassConfiguration.ConstantInfo;
import org.htmlunit.javascript.configuration.ClassConfiguration.PropertyInfo;
import org.htmlunit.javascript.configuration.JavaScriptConfiguration;
import org.htmlunit.javascript.configuration.ProxyAutoConfigJavaScriptConfiguration;
import org.htmlunit.javascript.host.ConsoleCustom;
import org.htmlunit.javascript.host.URLSearchParams;
import org.htmlunit.javascript.host.Window;
import org.htmlunit.javascript.host.WindowOrWorkerGlobalScope;
import org.htmlunit.javascript.host.dom.DOMException;
import org.htmlunit.javascript.host.html.HTMLElement;
import org.htmlunit.javascript.host.html.HTMLImageElement;
import org.htmlunit.javascript.host.html.HTMLOptionElement;
import org.htmlunit.javascript.host.intl.Intl;
import org.htmlunit.javascript.host.worker.WorkerGlobalScope;
import org.htmlunit.javascript.host.xml.FormData;
import org.htmlunit.javascript.polyfill.Polyfill;
import org.htmlunit.util.StringUtils;

/**
 * A wrapper for the <a href="http://www.mozilla.org/rhino">Rhino JavaScript engine</a>
 * that provides browser specific features.
 *
 * <p>Like all classes in this package, this class is not intended for direct use
 * and may change without notice.</p>
 *
 * @author Mike Bowler
 * @author Chen Jun
 * @author David K. Taylor
 * @author Chris Erskine
 * @author Ben Curren
 * @author David D. Kilzer
 * @author Marc Guillemot
 * @author Daniel Gredler
 * @author Ahmed Ashour
 * @author Amit Manjhi
 * @author Ronald Brill
 * @author Frank Danek
 * @author Lai Quang Duong
 * @author Sven Strickroth
 *
 * @see <a href="http://groups-beta.google.com/group/netscape.public.mozilla.jseng/browse_thread/thread/b4edac57329cf49f/069e9307ec89111f">
 *     Rhino and Java Browser</a>
 */
public class JavaScriptEngine implements AbstractJavaScriptEngine<Script> {

    private static final Log LOG = LogFactory.getLog(JavaScriptEngine.class);

    /** ScriptRuntime.emptyArgs. */
    public static final Object[] EMPTY_ARGS = ScriptRuntime.emptyArgs;

    /** org.htmlunit.corejs.javascript.Undefined.instance. */
    public static final Object UNDEFINED = org.htmlunit.corejs.javascript.Undefined.instance;

    private WebClient webClient_;
    private HtmlUnitContextFactory contextFactory_;
    private JavaScriptConfiguration jsConfig_;

    private transient ThreadLocal<Boolean> javaScriptRunning_;
    private transient ThreadLocal<List<PostponedAction>> postponedActions_;
    private transient boolean holdPostponedActions_;
    private transient boolean shutdownPending_;

    /** The JavaScriptExecutor corresponding to all windows of this Web client */
    private transient JavaScriptExecutor javaScriptExecutor_;

    /**
     * Key used to place the {@link HtmlPage} for which the JavaScript code is executed
     * as thread local attribute in current context.
     */
    public static final String KEY_STARTING_PAGE = "startingPage";

    /**
     * Creates an instance for the specified {@link WebClient}.
     *
     * @param webClient the client that will own this engine
     */
    public JavaScriptEngine(final WebClient webClient) {
        if (webClient == null) {
            throw new IllegalArgumentException("JavaScriptEngine ctor requires a webClient");
        }

        webClient_ = webClient;
        contextFactory_ = new HtmlUnitContextFactory(webClient);
        initTransientFields();

        jsConfig_ = JavaScriptConfiguration.getInstance(webClient.getBrowserVersion());
        RhinoException.setStackStyle(StackStyle.MOZILLA_LF);
    }

    /**
     * Returns the web client that this engine is associated with.
     * @return the web client
     */
    private WebClient getWebClient() {
        return webClient_;
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public HtmlUnitContextFactory getContextFactory() {
        return contextFactory_;
    }

    /**
     * Performs initialization for the given webWindow.
     * @param webWindow the web window to initialize for
     */
    @Override
    public void initialize(final WebWindow webWindow, final Page page) {
        WebAssert.notNull("webWindow", webWindow);

        if (shutdownPending_) {
            return;
        }

        getContextFactory().call(cx -> {
            try {
                init(webWindow, page, cx);
            }
            catch (final Exception e) {
                LOG.error("Exception while initializing JavaScript for the page", e);
                throw new ScriptException(null, e); // BUG: null is not useful.
            }
            return null;
        });
    }

    /**
     * Returns the JavaScriptExecutor.
     * @return the JavaScriptExecutor or null if javascript is disabled
     *         or no executor was required so far.
     */
    public JavaScriptExecutor getJavaScriptExecutor() {
        return javaScriptExecutor_;
    }

    /**
     * Initializes all the JS stuff for the window.
     * @param webWindow the web window
     * @param cx the current context
     * @throws Exception if something goes wrong
     */
    private void init(final WebWindow webWindow, final Page page, final Context cx) throws Exception {
        final WebClient webClient = getWebClient();
        final BrowserVersion browserVersion = webClient.getBrowserVersion();

        final Window jsWindow = new Window();
        jsWindow.setClassName("Window");

        final TopLevel scope = cx.initSafeStandardObjects(new TopLevel(jsWindow));
        jsWindow.setParentScope(scope);
        configureRhino(webClient, browserVersion, scope, jsWindow);

        final Map<Class<? extends Scriptable>, Scriptable> prototypes = new HashMap<>();
        final Map<String, Scriptable> prototypesPerJSName = new HashMap<>();

        final ClassConfiguration windowConfig = jsConfig_.getWindowClassConfiguration();
        final FunctionObject functionObject = new FunctionObject(jsWindow.getClassName(), windowConfig.getJsConstructor().getValue(), scope);
        ScriptableObject.defineProperty(jsWindow, "constructor", functionObject,
                ScriptableObject.DONTENUM  | ScriptableObject.PERMANENT | ScriptableObject.READONLY);

        configureConstantsPropertiesAndFunctions(windowConfig, scope, jsWindow);

        final HtmlUnitScriptable windowPrototype = configureClass(windowConfig, scope);
        jsWindow.setPrototype(windowPrototype);
        prototypes.put(windowConfig.getHostClass(), windowPrototype);
        prototypesPerJSName.put(windowConfig.getClassName(), windowPrototype);

        configureGlobalThis(scope, jsWindow, windowConfig, functionObject, jsConfig_, browserVersion, prototypes, prototypesPerJSName);

        // TODO remove the cast
        URLSearchParams.NativeParamsIterator.init(cx, scope, "URLSearchParams Iterator");
        FormData.FormDataIterator.init(cx, scope, "FormData Iterator");

        // strange but this is the reality for browsers
        // because there will be still some sites using this for browser detection the property is
        // set to null
        // https://stackoverflow.com/questions/9847580/how-to-detect-safari-chrome-ie-firefox-and-opera-browsers
        // https://bugzilla.mozilla.org/show_bug.cgi?id=1442035
        if (browserVersion.hasFeature(JS_WINDOW_INSTALL_TRIGGER_NULL)) {
            jsWindow.put("InstallTrigger", jsWindow, null);
        }

        // special handling for image/option
        final Method imageCtor = HTMLImageElement.class.getDeclaredMethod("jsConstructorImage");
        additionalCtor(scope, jsWindow, prototypesPerJSName.get("HTMLImageElement"), imageCtor, "Image", "HTMLImageElement");
        final Method optionCtor = HTMLOptionElement.class.getDeclaredMethod("jsConstructorOption",
                Object.class, String.class, boolean.class, boolean.class);
        additionalCtor(scope, jsWindow, prototypesPerJSName.get("HTMLOptionElement"), optionCtor, "Option", "HTMLOptionElement");

        if (!webClient.getOptions().isWebSocketEnabled()) {
            deleteProperties(jsWindow, "WebSocket");
        }

        jsWindow.setPrototypes(prototypes);
        jsWindow.initialize(scope, webWindow, page);

        applyPolyfills(webClient, browserVersion, cx, scope, jsWindow);
    }

    /**
     * <span style="color:red">INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.</span><br>
     *
     * @param scope the scope
     * @param globalThis the globalThis to set up
     * @param scopeConfig the {@link ClassConfiguration} that is used for the scope
     * @param scopeContructorFunctionObject the (already registered) ctor
     * @param jsConfig the complete jsConfig
     * @param browserVersion the {@link BrowserVersion}
     * @param prototypes map of prototypes
     * @param prototypesPerJSName map of prototypes with the class name as key
     * @throws Exception in case of error
     */
    public static void configureGlobalThis(
            final TopLevel scope,
            final HtmlUnitScriptable globalThis,
            final ClassConfiguration scopeConfig,
            final FunctionObject scopeContructorFunctionObject,
            final AbstractJavaScriptConfiguration jsConfig,
            final BrowserVersion browserVersion,
            final Map<Class<? extends Scriptable>, Scriptable> prototypes,
            final Map<String, Scriptable> prototypesPerJSName) throws Exception {

        final Scriptable objectPrototype = ScriptableObject.getObjectPrototype(scope);

        final Map<String, Function> ctorPrototypesPerJSName = new HashMap<>();
        for (final ClassConfiguration config : jsConfig.getAll()) {
            final String jsClassName = config.getClassName();
            Scriptable prototype = prototypesPerJSName.get(jsClassName);
            final String extendedClassName =
                    StringUtils.isEmptyOrNull(config.getExtendedClassName()) ? null : config.getExtendedClassName();

            // setup the prototypes
            if (config == scopeConfig) {
                if (extendedClassName == null) {
                    prototype.setPrototype(objectPrototype);
                }
                else {
                    prototype.setPrototype(prototypesPerJSName.get(extendedClassName));
                }

                // setup constructors
                addAsConstructorAndAlias(scopeContructorFunctionObject, scope, globalThis, prototype, config);
                configureConstantsStaticPropertiesAndStaticFunctions(config, scope, scopeContructorFunctionObject);

                // adjust prototype if needed
                if (extendedClassName != null) {
                    scopeContructorFunctionObject.setPrototype(ctorPrototypesPerJSName.get(extendedClassName));
                }
            }
            else if (config.getDescriptor() != null) {
                // Descriptor-based path (ClassDescriptor API)
                final HtmlUnitScriptable classPrototype = config.getHostClass().getDeclaredConstructor().newInstance();
                classPrototype.setParentScope(scope);
                classPrototype.setClassName(jsClassName);

                // buildConstructor wires up all methods/properties, sets proto.__proto__ to Object.prototype,
                // and registers the constructor in the scope (which routes to globalThis via TopLevel.put)
                final JSFunction ctor = config.getDescriptor().buildConstructor(
                        Context.getCurrentContext(), scope, classPrototype, false);
                ctorPrototypesPerJSName.put(jsClassName, ctor);

                // Override proto chain after buildConstructor (it defaults to Object.prototype)
                if (extendedClassName != null) {
                    classPrototype.setPrototype(prototypesPerJSName.get(extendedClassName));
                    ctor.setPrototype(ctorPrototypesPerJSName.get(extendedClassName));
                }

                prototypes.put(config.getHostClass(), classPrototype);
                prototypesPerJSName.put(jsClassName, classPrototype);

                // Add Symbol.toStringTag to match the annotation-based setup in process()
                ScriptableObject.defineProperty(classPrototype, SymbolKey.TO_STRING_TAG, jsClassName,
                        ScriptableObject.DONTENUM | ScriptableObject.READONLY);

                if (!config.isJsObject()) {
                    // buildConstructor registers the ctor in the scope (→ globalThis), so remove it
                    globalThis.delete(jsClassName);
                }

                final String alias = config.getJsConstructorAlias();
                if (alias != null) {
                    ScriptableObject.defineProperty(globalThis, alias, ctor, ScriptableObject.DONTENUM);
                }
            }
            else {
                final HtmlUnitScriptable classPrototype = configureClass(config, scope);
                prototypes.put(config.getHostClass(), classPrototype);
                prototypesPerJSName.put(jsClassName, classPrototype);
                prototype = classPrototype;

                if (extendedClassName == null) {
                    classPrototype.setPrototype(objectPrototype);
                }
                else {
                    classPrototype.setPrototype(prototypesPerJSName.get(extendedClassName));
                }

                // setup constructors
                if (prototype != null) {
                    final Map.Entry<String, Member> jsConstructor = config.getJsConstructor();
                    if (jsConstructor == null) {
                        final HtmlUnitScriptable constructor = config.getHostClass().getDeclaredConstructor().newInstance();
                        constructor.setClassName(jsClassName);
                        defineConstructor(scope, prototype, constructor);
                        configureConstantsStaticPropertiesAndStaticFunctions(config, scope, constructor);

                        if (config.isJsObject()) {
                            globalThis.defineProperty(jsClassName, constructor, ScriptableObject.DONTENUM);
                        }
                    }
                    else {
                        final FunctionObject function = new FunctionObject(jsConstructor.getKey(), jsConstructor.getValue(), scope);
                        ctorPrototypesPerJSName.put(jsClassName, function);

                        addAsConstructorAndAlias(function, scope, globalThis, prototype, config);
                        configureConstantsStaticPropertiesAndStaticFunctions(config, scope, function);

                        if (!config.isJsObject()) {
                            // addAsConstructorAndAlias(..) calls addAsConstructor() from core-js
                            // addAsConstructor(..) registeres the ctor in the scope already
                            // therefore we have to remove here
                            globalThis.delete(prototype.getClassName());
                        }

                        // adjust prototype if needed
                        if (extendedClassName != null) {
                            function.setPrototype(ctorPrototypesPerJSName.get(extendedClassName));
                        }
                    }
                }
            }
        }
    }

    private static void addAsConstructorAndAlias(final FunctionObject function,
            final VarScope scope,
            final HtmlUnitScriptable destination,
            final Scriptable prototype,
            final ClassConfiguration config) {
        try {
            function.addAsConstructor(scope, prototype, ScriptableObject.DONTENUM);

            final String alias = config.getJsConstructorAlias();
            if (alias != null) {
                ScriptableObject.defineProperty(destination, alias, function, ScriptableObject.DONTENUM);
            }
        }
        catch (final Exception e) {
            // TODO see issue #1897
            if (LOG.isWarnEnabled()) {
                final String newline = System.lineSeparator();
                LOG.warn("Error during JavaScriptEngine.init(WebWindow, Context)" + newline
                        + e.getMessage() + newline
                        + "prototype: " + prototype.getClassName(), e);
            }
        }
    }

    private static void additionalCtor(final VarScope scope, final Window window, final Scriptable proto,
            final Method ctorMethod, final String prop, final String clazzName) throws Exception {
        final FunctionObject function = new FunctionObject(prop, ctorMethod, scope);
        final Object prototypeProperty = ScriptableObject.getProperty(window, clazzName);
        try {
            function.addAsConstructor(scope, proto, ScriptableObject.DONTENUM);
        }
        catch (final Exception e) {
            // TODO see issue #1897
            if (LOG.isWarnEnabled()) {
                final String newline = System.lineSeparator();
                LOG.warn("Error during JavaScriptEngine.init(WebWindow, Context)" + newline
                        + e.getMessage() + newline
                        + "prototype: " + proto.getClassName(), e);
            }
        }
        ScriptableObject.defineProperty(window, prop, function, ScriptableObject.DONTENUM);
        ScriptableObject.defineProperty(window, clazzName, prototypeProperty, ScriptableObject.DONTENUM);
    }

    /**
     * <span style="color:red">INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.</span><br>
     *
     * @param webClient the WebClient
     * @param browserVersion the BrowserVersion
     * @param scope the scope
     * @param globalThis the window or the DedicatedWorkerGlobalScope
     */
    public static void configureRhino(final WebClient webClient, final BrowserVersion browserVersion,
            final TopLevel scope, final HtmlUnitScriptable globalThis) {

        // this should be like
        // NativeConsole.init(scope, globalThis, false, webClient.getWebConsole());
        // but so far both objects are the same
        NativeConsole.init(scope, false, webClient.getWebConsole());

        // https://developer.mozilla.org/en-US/docs/Web/API/console/timeStamp_static
        // this is not standard and therefore not in Rhino
        final ScriptableObject console = (ScriptableObject) ScriptableObject.getProperty(globalThis, "console");
        console.defineFunctionProperties(scope, new String[] {"timeStamp"}, ConsoleCustom.class, ScriptableObject.DONTENUM);

        // remove some objects, that Rhino defines in top scope but that we don't want
        deleteProperties(globalThis, "Continuation", "StopIteration", "uneval", "global", "__GeneratorFunction");

        // Rhino defines too many methods for us, particularly since implementation of ECMAScript5
        final ScriptableObject stringPrototype = (ScriptableObject) ScriptableObject.getClassPrototype(scope, "String");
        deleteProperties(stringPrototype, "equals", "equalsIgnoreCase", "toSource");

        final ScriptableObject numberPrototype = (ScriptableObject) ScriptableObject.getClassPrototype(scope, "Number");
        deleteProperties(numberPrototype, "toSource");
        final ScriptableObject datePrototype = (ScriptableObject) ScriptableObject.getClassPrototype(scope, "Date");
        deleteProperties(datePrototype, "toSource");

        removePrototypeProperties(scope, "Object", "toSource");
        removePrototypeProperties(scope, "Array", "toSource");
        removePrototypeProperties(scope, "Function", "toSource");

        deleteProperties(globalThis, "isXMLName");

        NativeFunctionToStringFunction.installFix(scope, browserVersion);

        final ScriptableObject errorObject = (ScriptableObject) ScriptableObject.getProperty(globalThis, "Error");
        if (browserVersion.hasFeature(JS_ERROR_STACK_TRACE_LIMIT)) {
            errorObject.defineProperty("stackTraceLimit", 10, ScriptableObject.EMPTY);
        }
        else {
            ScriptableObject.deleteProperty(errorObject, "stackTraceLimit");
        }

        // add Intl
        Intl.init(scope, globalThis, browserVersion);
    }

    /**
     * <span style="color:red">INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.</span><br>
     *
     * @param webClient the WebClient
     * @param browserVersion the BrowserVersion
     * @param context the current context
     * @param scope the scope
     * @param scriptable the window or the DedicatedWorkerGlobalScope
     * @throws IOException in case of problems
     */
    public static void applyPolyfills(final WebClient webClient, final BrowserVersion browserVersion,
            final Context context, final VarScope scope, final HtmlUnitScriptable scriptable) throws IOException {

        if (webClient.getOptions().isFetchPolyfillEnabled()) {
            Polyfill.getFetchPolyfill().apply(context, scope, scriptable);
        }
    }

    private static void defineConstructor(final VarScope scope,
            final Scriptable prototype, final ScriptableObject constructor) {
        constructor.setParentScope(scope);
        try {
            ScriptableObject.defineProperty(prototype, "constructor", constructor,
                    ScriptableObject.DONTENUM  | ScriptableObject.PERMANENT | ScriptableObject.READONLY);
        }
        catch (final Exception e) {
            // TODO see issue #1897
            if (LOG.isWarnEnabled()) {
                final String newline = System.lineSeparator();
                LOG.warn("Error during JavaScriptEngine.init(WebWindow, Context)" + newline
                        + e.getMessage() + newline
                        + "prototype: " + prototype.getClassName(), e);
            }
        }

        try {
            ScriptableObject.defineProperty(constructor, "prototype", prototype,
                    ScriptableObject.DONTENUM  | ScriptableObject.PERMANENT | ScriptableObject.READONLY);
        }
        catch (final Exception e) {
            // TODO see issue #1897
            if (LOG.isWarnEnabled()) {
                final String newline = System.lineSeparator();
                LOG.warn("Error during JavaScriptEngine.init(WebWindow, Context)" + newline
                        + e.getMessage() + newline
                        + "prototype: " + prototype.getClassName(), e);
            }
        }
    }

    /**
     * Deletes the properties with the provided names.
     * @param destination the object from which the properties are to be removed
     * @param propertiesToDelete the list of property names
     */
    private static void deleteProperties(final Scriptable destination, final String... propertiesToDelete) {
        for (final String property : propertiesToDelete) {
            destination.delete(property);
        }
    }

    /**
     * Removes prototype properties.
     * @param scope the scope to search for the prototype
     * @param className the class for which properties should be removed
     * @param properties the properties to remove
     */
    private static void removePrototypeProperties(final VarScope scope, final String className,
            final String... properties) {
        final ScriptableObject prototype = (ScriptableObject) ScriptableObject.getClassPrototype(scope, className);
        for (final String property : properties) {
            prototype.delete(property);
        }
    }

    /**
     * Configures the specified class for access via JavaScript.
     * @param config the configuration settings for the class to be configured
     * @param scope the scope to configure within which to configure the class
     * @throws InstantiationException if the new class cannot be instantiated
     * @throws IllegalAccessException if we don't have access to create the new instance
     * @return the created prototype
     * @throws Exception in case of errors
     */
    public static HtmlUnitScriptable configureClass(final ClassConfiguration config,
            final TopLevel scope)
        throws Exception {

        final HtmlUnitScriptable prototype = config.getHostClass().getDeclaredConstructor().newInstance();
        prototype.setParentScope(scope);
        prototype.setClassName(config.getClassName());

        configureConstantsPropertiesAndFunctions(config, scope, prototype);

        return prototype;
    }

    /**
     * Configures constants, static properties and static functions on the object.
     * @param config the configuration for the object
     * @param scriptable the object to configure
     */
    private static void configureConstantsStaticPropertiesAndStaticFunctions(final ClassConfiguration config,
            final TopLevel scope, final ScriptableObject scriptable) {
        configureConstants(config, scriptable);
        configureStaticProperties(config, scope, scriptable);
        configureStaticFunctions(config, scope, scriptable);
    }

    /**
     * Configures constants, properties and functions on the object.
     * @param config the configuration for the object
     * @param scope the scope
     * @param scriptable the object to configure
     */
    private static void configureConstantsPropertiesAndFunctions(final ClassConfiguration config,
            final TopLevel scope, final ScriptableObject scriptable) {
        configureConstants(config, scriptable);
        configureProperties(config, scope, scriptable);
        configureFunctions(config, scope, scriptable);
        configureSymbolConstants(config, scriptable);
        configureSymbols(config, scope, scriptable);
    }

    private static void configureFunctions(final ClassConfiguration config,
            final TopLevel scope, final ScriptableObject scriptable) {
        // the functions
        final Map<String, Method> functionMap = config.getFunctionMap();
        if (functionMap != null) {
            for (final Entry<String, Method> functionInfo : functionMap.entrySet()) {
                final String functionName = functionInfo.getKey();
                final Method method = functionInfo.getValue();
                final FunctionObject functionObject = new FunctionObject(functionName, method, scope);
                scriptable.defineProperty(functionName, functionObject, ScriptableObject.EMPTY);
            }
        }
    }

    private static void configureConstants(final ClassConfiguration config, final ScriptableObject scriptable) {
        final List<ConstantInfo> constants = config.getConstants();
        if (constants != null) {
            for (final ConstantInfo constantInfo : constants) {
                scriptable.defineProperty(constantInfo.getName(), constantInfo.getValue(), constantInfo.getFlag());
            }
        }
    }

    private static void configureProperties(final ClassConfiguration config,
            final TopLevel scope, final ScriptableObject scriptable) {
        final Map<String, PropertyInfo> propertyMap = config.getPropertyMap();
        if (propertyMap != null) {
            for (final Entry<String, PropertyInfo> propertyEntry : propertyMap.entrySet()) {
                final PropertyInfo info = propertyEntry.getValue();
                final Method readMethod = info.getReadMethod();
                final Method writeMethod = info.getWriteMethod();
                scriptable.defineProperty(scope, propertyEntry.getKey(), null, readMethod, writeMethod, ScriptableObject.EMPTY);
            }
        }
    }

    private static void configureStaticProperties(final ClassConfiguration config,
            final TopLevel scope, final ScriptableObject scriptable) {
        final Map<String, PropertyInfo> staticPropertyMap = config.getStaticPropertyMap();
        if (staticPropertyMap != null) {
            for (final Entry<String, ClassConfiguration.PropertyInfo> propertyEntry : staticPropertyMap.entrySet()) {
                final String propertyName = propertyEntry.getKey();
                final Method readMethod = propertyEntry.getValue().getReadMethod();
                final Method writeMethod = propertyEntry.getValue().getWriteMethod();
                final int flag = ScriptableObject.EMPTY;

                scriptable.defineProperty(scope, propertyName, null, readMethod, writeMethod, flag);
            }
        }
    }

    private static void configureStaticFunctions(final ClassConfiguration config,
            final TopLevel scope, final ScriptableObject scriptable) {
        final Map<String, Method> staticFunctionMap = config.getStaticFunctionMap();
        if (staticFunctionMap != null) {
            for (final Entry<String, Method> staticFunctionInfo : staticFunctionMap.entrySet()) {
                final String functionName = staticFunctionInfo.getKey();
                final Method method = staticFunctionInfo.getValue();
                final FunctionObject staticFunctionObject = new FunctionObject(functionName, method, scope);
                scriptable.defineProperty(functionName, staticFunctionObject, ScriptableObject.EMPTY);
            }
        }
    }

    private static void configureSymbolConstants(final ClassConfiguration config, final ScriptableObject scriptable) {
        final Map<Symbol, String> symbolConstantMap = config.getSymbolConstantMap();
        if (symbolConstantMap != null) {
            for (final Entry<Symbol, String> symbolInfo : symbolConstantMap.entrySet()) {
                scriptable.defineProperty(symbolInfo.getKey(), symbolInfo.getValue(), ScriptableObject.DONTENUM | ScriptableObject.READONLY);
            }
        }
    }

    private static void configureSymbols(final ClassConfiguration config,
            final TopLevel scope, final ScriptableObject scriptable) {
        final Map<Symbol, Method> symbolMap = config.getSymbolMap();
        if (symbolMap != null) {
            for (final Entry<Symbol, Method> symbolInfo : symbolMap.entrySet()) {
                final Symbol symbol = symbolInfo.getKey();
                final Method method = symbolInfo.getValue();
                final String methodName = method.getName();

                final Callable symbolFunction;
                // a bit strange but this avoid the has call and therefore saves one lookup
                final Object property = scriptable.get(methodName, scriptable);
                if (property == Scriptable.NOT_FOUND) {
                    symbolFunction = new FunctionObject(methodName, method, scope);
                }
                else {
                    symbolFunction = (Callable) property;
                }
                scriptable.defineProperty(symbol, symbolFunction, ScriptableObject.DONTENUM);
            }
        }
    }

    /**
     * Register WebWindow with the JavaScriptExecutor.
     * @param webWindow the WebWindow to be registered.
     */
    @Override
    public synchronized void registerWindowAndMaybeStartEventLoop(final WebWindow webWindow) {
        if (shutdownPending_) {
            return;
        }

        final WebClient webClient = getWebClient();
        if (webClient != null) {
            if (javaScriptExecutor_ == null) {
                javaScriptExecutor_ = BackgroundJavaScriptFactory.theFactory().createJavaScriptExecutor(webClient);
            }
            javaScriptExecutor_.addWindow(webWindow);
        }
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public void prepareShutdown() {
        shutdownPending_ = true;
    }

    /**
     * Shutdown the JavaScriptEngine.
     */
    @Override
    public void shutdown() {
        webClient_ = null;
        contextFactory_ = null;
        jsConfig_ = null;

        if (javaScriptExecutor_ != null) {
            javaScriptExecutor_.shutdown();
            javaScriptExecutor_ = null;
        }
        if (postponedActions_ != null) {
            postponedActions_.remove();
        }
        if (javaScriptRunning_ != null) {
            javaScriptRunning_.remove();
        }
        holdPostponedActions_ = false;
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public Script compile(final HtmlPage owningPage, final VarScope scope, final String sourceCode,
            final String sourceName, final int startLine) {
        WebAssert.notNull("sourceCode", sourceCode);

        if (LOG.isTraceEnabled()) {
            final String newline = System.lineSeparator();
            LOG.trace("Javascript compile " + sourceName + newline + sourceCode + newline);
        }

        final HtmlUnitCompileContextAction action = new HtmlUnitCompileContextAction(owningPage, sourceCode, sourceName, startLine);
        return (Script) getContextFactory().callSecured(action, owningPage);
    }

    /**
     * Forwards this to the {@link HtmlUnitContextFactory} but with checking shutdown handling.
     *
     * @param <T> return type of the action
     * @param action the contextAction
     * @param page the page
     * @return the result of the call
     */
    public final <T> T callSecured(final ContextAction<T> action, final HtmlPage page) {
        if (shutdownPending_ || webClient_ == null) {
            // shutdown was already called
            return null;
        }

        return getContextFactory().callSecured(action, page);
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public Object execute(final HtmlPage page,
                           final VarScope scope,
                           final String sourceCode,
                           final String sourceName,
                           final int startLine) {
        final Script script = compile(page, scope, sourceCode, sourceName, startLine);
        if (script == null) {
            // happens with syntax error + throwExceptionOnScriptError = false
            return null;
        }
        return execute(page, scope, script);
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public Object execute(final HtmlPage page, final VarScope scope, final Script script) {
        if (shutdownPending_ || webClient_ == null) {
            // shutdown was already called
            return null;
        }

        final HtmlUnitContextAction action = new HtmlUnitContextAction(page) {
            @Override
            public Object doRun(final Context cx) {
                return script.exec(cx, scope, ScriptableObject.getTopLevelScope(scope).getGlobalThis());
            }

            @Override
            protected String getSourceCode(final Context cx) {
                return null;
            }
        };

        return getContextFactory().callSecured(action, page);
    }

    /**
     * Calls a JavaScript function and return the result.
     * @param page the page
     * @param javaScriptFunction the function to call
     * @param thisObject the this object for class method calls
     * @param args the list of arguments to pass to the function
     * @param node the HTML element that will act as the context
     * @return the result of the function call
     */
    public Object callFunction(
            final HtmlPage page,
            final Function javaScriptFunction,
            final Scriptable thisObject,
            final Object[] args,
            final DomNode node) {

        VarScope scope = ScriptableObject.getTopLevelScope(thisObject.getParentScope());

        if (node != null && node instanceof HtmlElement htmlElement) {
            final HTMLElement elem = htmlElement.getScriptableObject();
            scope = new WithScope(scope, elem.getOwnerDocument());

            if (htmlElement instanceof SubmittableElement) {
                final HtmlForm enclosingForm = htmlElement.getEnclosingForm();
                if (enclosingForm != null) {
                    scope = new WithScope(scope, enclosingForm.getScriptableObject());
                }
            }

            scope = new WithScope(scope, node.getScriptableObject());
        }

        return callFunction(page, javaScriptFunction, scope, thisObject, args);
    }

    /**
     * Calls the given function taking care of synchronization issues.
     * @param page the interactive page that caused this script to executed
     * @param function the JavaScript function to execute
     * @param scope the execution scope
     * @param thisObject the 'this' object
     * @param args the function's arguments
     * @return the function result
     */
    public Object callFunction(final HtmlPage page, final Function function,
            final VarScope scope, final Scriptable thisObject, final Object[] args) {
        if (shutdownPending_ || webClient_ == null) {
            // shutdown was already called
            return null;
        }

        final HtmlUnitContextAction action = new HtmlUnitContextAction(page) {
            @Override
            public Object doRun(final Context cx) {
                if (ScriptRuntime.hasTopCall(cx)) {
                    return function.call(cx, scope, thisObject, args);
                }
                return ScriptRuntime.doTopCall(function, cx, scope, thisObject, args, cx.isStrictMode());
            }
            @Override
            protected String getSourceCode(final Context cx) {
                return cx.decompileFunction(function, 2);
            }
        };
        return getContextFactory().callSecured(action, page);
    }

    /**
     * Indicates if JavaScript is running in current thread.
     * <p>This allows code to know if their own evaluation has been triggered by some JS code.
     * @return {@code true} if JavaScript is running
     */
    @Override
    public boolean isScriptRunning() {
        return Boolean.TRUE.equals(javaScriptRunning_.get());
    }

    /**
     * Special ContextAction only for compiling. This reduces some code and avoid
     * some calls.
     */
    private final class HtmlUnitCompileContextAction implements ContextAction<Object> {
        private final HtmlPage page_;
        private final String sourceCode_;
        private final String sourceName_;
        private final int startLine_;

        HtmlUnitCompileContextAction(final HtmlPage page, final String sourceCode, final String sourceName, final int startLine) {
            page_ = page;
            sourceCode_ = sourceCode;
            sourceName_ = sourceName;
            startLine_ = startLine;
        }

        @Override
        public Object run(final Context cx) {
            try {
                final Object response;
                cx.putThreadLocal(KEY_STARTING_PAGE, page_);
                synchronized (page_) { // 2 scripts can't be executed in parallel for one page
                    if (page_ != page_.getEnclosingWindow().getEnclosedPage()) {
                        return null; // page has been unloaded
                    }
                    response = cx.compileString(sourceCode_, sourceName_, startLine_, null);

                }

                return response;
            }
            catch (final Exception e) {
                handleJavaScriptException(new ScriptException(page_, e, sourceCode_), true);
                return null;
            }
            catch (final TimeoutError e) {
                handleJavaScriptTimeoutError(page_, e);
                return null;
            }
        }
    }

    /**
     * Facility for ContextAction usage.
     * ContextAction should be preferred because according to Rhino doc it
     * "guarantees proper association of Context instances with the current thread and is faster".
     */
    private abstract class HtmlUnitContextAction implements ContextAction<Object> {
        private final HtmlPage page_;

        HtmlUnitContextAction(final HtmlPage page) {
            page_ = page;
        }

        @Override
        public final Object run(final Context cx) {
            final Boolean javaScriptAlreadyRunning = javaScriptRunning_.get();
            javaScriptRunning_.set(Boolean.TRUE);

            try {
                final Object response;
                synchronized (page_) { // 2 scripts can't be executed in parallel for one page
                    if (page_ != page_.getEnclosingWindow().getEnclosedPage()) {
                        return null; // page has been unloaded
                    }
                    response = doRun(cx);
                }

                cx.processMicrotasks();

                // doProcessPostponedActions is synchronized
                // moved out of the sync block to avoid deadlocks
                if (!holdPostponedActions_) {
                    doProcessPostponedActions();
                }

                return response;
            }
            catch (final Exception e) {
                handleJavaScriptException(new ScriptException(page_, e, getSourceCode(cx)), true);
                return null;
            }
            catch (final TimeoutError e) {
                handleJavaScriptTimeoutError(page_, e);
                return null;
            }
            finally {
                javaScriptRunning_.set(javaScriptAlreadyRunning);
            }
        }

        protected abstract Object doRun(Context cx);

        protected abstract String getSourceCode(Context cx);
    }

    private void doProcessPostponedActions() {
        holdPostponedActions_ = false;

        final WebClient webClient = getWebClient();
        if (webClient == null) {
            // shutdown was already called
            postponedActions_.set(null);
            return;
        }

        try {
            webClient.loadDownloadedResponses();
        }
        catch (final RuntimeException e) {
            throw e;
        }
        catch (final Exception e) {
            throw new RuntimeException(e);
        }

        final List<PostponedAction> actions = postponedActions_.get();
        if (actions != null && !actions.isEmpty()) {
            postponedActions_.set(new ArrayList<>());
            try {
                for (final PostponedAction action : actions) {
                    if (LOG.isDebugEnabled()) {
                        LOG.debug("Processing PostponedAction " + action);
                    }

                    // verify that the page that registered this PostponedAction is still alive
                    if (action.isStillAlive()) {
                        action.execute();
                    }
                }
            }
            catch (final RuntimeException e) {
                throw e;
            }
            catch (final Exception e) {
                throw JavaScriptEngine.throwAsScriptRuntimeEx(e);
            }
        }
    }

    /**
     * Adds an action that should be executed first when the script currently being executed has finished.
     * @param action the action
     */
    @Override
    public void addPostponedAction(final PostponedAction action) {
        if (shutdownPending_) {
            return;
        }

        List<PostponedAction> actions = postponedActions_.get();
        if (actions == null) {
            actions = new ArrayList<>();
            postponedActions_.set(actions);
        }
        actions.add(action);
    }

    /**
     * Handles an exception that occurred during execution of JavaScript code.
     * @param scriptException the exception
     * @param triggerOnError if true, this triggers the onerror handler
     */
    protected void handleJavaScriptException(final ScriptException scriptException, final boolean triggerOnError) {
        final WebClient webClient = getWebClient();
        if (shutdownPending_ || webClient == null) {
            // shutdown was already called
            return;
        }

        // Trigger window.onerror, if it has been set.
        final HtmlPage page = scriptException.getPage();
        if (triggerOnError && page != null) {
            final WebWindow window = page.getEnclosingWindow();
            if (window != null) {
                final Window w = window.getScriptableObject();
                if (w != null) {
                    try {
                        w.triggerOnError(scriptException);
                    }
                    catch (final Exception e) {
                        handleJavaScriptException(new ScriptException(page, e, null), false);
                    }
                }
            }
        }

        webClient.getJavaScriptErrorListener().scriptException(page, scriptException);
        // Throw a Java exception if the user wants us to.
        if (webClient.getOptions().isThrowExceptionOnScriptError()) {
            throw scriptException;
        }
    }

    /**
     * Handles an exception that occurred during execution of JavaScript code.
     * @param page the page in which the script causing this exception was executed
     * @param e the timeout error that was thrown from the script engine
     */
    protected void handleJavaScriptTimeoutError(final HtmlPage page, final TimeoutError e) {
        final WebClient webClient = getWebClient();
        if (shutdownPending_ || webClient == null) {
            // shutdown was already called
            return;
        }

        webClient.getJavaScriptErrorListener().timeoutError(page, e.getAllowedTime(), e.getExecutionTime());
        if (webClient.getOptions().isThrowExceptionOnScriptError()) {
            throw new RuntimeException(e);
        }
        LOG.info("Caught script timeout error", e);
    }

    /**
     * <span style="color:red">INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.</span><br>
     * Indicates that no postponed action should be executed.
     */
    @Override
    public void holdPosponedActions() {
        holdPostponedActions_ = true;
    }

    /**
     * <span style="color:red">INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.</span><br>
     * Process postponed actions, if any.
     */
    @Override
    public void processPostponedActions() {
        doProcessPostponedActions();
    }

    /**
     * Re-initializes transient fields when an object of this type is deserialized.
     */
    private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
        in.defaultReadObject();
        initTransientFields();
    }

    private void initTransientFields() {
        javaScriptRunning_ = new ThreadLocal<>();
        postponedActions_ = new ThreadLocal<>();
        holdPostponedActions_ = false;
        shutdownPending_ = false;
    }

    /**
     * Gets the class of the JavaScript object for the node class.
     * @param c the node class {@link DomNode} or some subclass.
     * @return {@code null} if none found
     */
    public Class<? extends HtmlUnitScriptable> getJavaScriptClass(final Class<?> c) {
        return jsConfig_.getDomJavaScriptMappingFor(c);
    }

    /**
     * Gets the associated configuration.
     * @return the configuration
     */
    @Override
    public JavaScriptConfiguration getJavaScriptConfiguration() {
        return jsConfig_;
    }

    /**
     * Returns the javascript timeout.
     * @return the javascript timeout
     */
    @Override
    public long getJavaScriptTimeout() {
        return getContextFactory().getTimeout();
    }

    /**
     * Sets the javascript timeout.
     * @param timeout the timeout
     */
    @Override
    public void setJavaScriptTimeout(final long timeout) {
        getContextFactory().setTimeout(timeout);
    }

    /**
     * Convert the value to a JavaScript Number value.
     *
     * @param value a JavaScript value
     * @return the corresponding double value converted using the ECMA rules
     */
    public static double toNumber(final Object value) {
        return ScriptRuntime.toNumber(value);
    }

    /**
     * Convert the value to a JavaScript String value.
     *
     * @param value a JavaScript value
     * @return the corresponding String value converted using the ECMA rules
     */
    public static String toString(final Object value) {
        return ScriptRuntime.toString(value);
    }

    /**
     * Convert the value to a JavaScript boolean value.
     *
     * @param value a JavaScript value
     * @return the corresponding boolean value converted using the ECMA rules
     */
    public static boolean toBoolean(final Object value) {
        return ScriptRuntime.toBoolean(value);
    }

    /**
     * Rethrow the exception wrapping it as the script runtime exception.
     *
     * @param e the exception to rethrow
     * @return RuntimeException as dummy the method always throws
     */
    public static RuntimeException throwAsScriptRuntimeEx(final Throwable e) {
        throw Context.throwAsScriptRuntimeEx(e);
    }

    /**
     * Report a runtime error using the error reporter for the current thread.
     *
     * @param message the error message to report
     * @return RuntimeException as dummy the method always throws
     */
    public static RuntimeException reportRuntimeError(final String message) {
        throw Context.reportRuntimeError(message);
    }

    /**
     * Report a runtime error using the error reporter for the current thread.
     *
     * @param message the error message to report
     * @return EcmaError
     */
    public static EcmaError syntaxError(final String message) {
        return ScriptRuntime.syntaxError(message);
    }

    /**
     * Report a runtime error using the error reporter for the current thread.
     *
     * @param message the error message to report
     * @return EcmaError
     */
    public static EcmaError typeError(final String message) {
        return ScriptRuntime.typeError(message);
    }

    /**
     * Report a TypeError with the message "Illegal constructor.".
     *
     * @return EcmaError
     */
    public static EcmaError typeErrorIllegalConstructor() {
        throw JavaScriptEngine.typeError("Illegal constructor.");
    }

    /**
     * Report a runtime error using the error reporter for the current thread.
     *
     * @param message the error message to report
     * @return EcmaError
     */
    public static EcmaError rangeError(final String message) {
        return ScriptRuntime.rangeError(message);
    }

    /**
     * @param error the error
     * @param message the message
     * @return a new EcmaError
     */
    public static EcmaError constructError(final String error, final String message) {
        return ScriptRuntime.constructError(error, message);
    }

    /**
     * <span style="color:red">INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.</span><br>
     *
     * Creates a {@link DOMException} and encapsulates it into a Rhino-compatible exception.
     *
     * @param scriptable the scriptable triggering this
     * @param message the exception message
     * @param type the exception type
     * @return the created exception
     */
    public static RhinoException asJavaScriptException(final HtmlUnitScriptable scriptable, final String message, final int type) {
        final DOMException domException = new DOMException(message, type);
        domException.setParentScope(scriptable.getParentScope());

        final WindowOrWorkerGlobalScope wow = HtmlUnitScriptable.getWindowOrWorkerGlobalScope(scriptable);
        if (wow instanceof Window window) {
            domException.setPrototype(window.getPrototype(DOMException.class));
        }
        else if (wow instanceof WorkerGlobalScope w) {
            domException.setPrototype(w.getPrototype(DOMException.class));
        }

        final EcmaError helper = ScriptRuntime.syntaxError("helper");
        String fileName = helper.sourceName();
        if (fileName != null) {
            fileName = fileName.replaceFirst("script in (.*) from .*", "$1");
        }
        domException.setLocation(fileName, helper.lineNumber());

        return new JavaScriptException(domException, fileName, helper.lineNumber());
    }

    /**
     * Todo.
     *
     * @param fn the function
     * @param cx the context
     * @param scope the scope
     */
    public static void setFunctionProtoAndParent(final BaseFunction fn, final Context cx, final VarScope scope) {
        ScriptRuntime.setFunctionProtoAndParent(fn, cx, scope);
    }

    /**
     * Create a new javascript object by calling the ctor with the provided args.
     *
     * @param scope the scope to create the object in
     * @param constructorName the name of the ctor function to call
     * @param args the args
     * @return the new object
     */
    public static Scriptable newObject(final VarScope scope, final String constructorName, final Object[] args) {
        return ScriptRuntime.newObject(Context.getCurrentContext(), scope, constructorName, args);
    }

    /**
     * Create a new JavaScript object.
     *
     * <p>Equivalent to evaluating "new Object()".
     *
     * @param scope the scope to search for the constructor and to evaluate against
     * @return the new object
     */
    public static Scriptable newObject(final VarScope scope) {
        final NativeObject result = new NativeObject();
        ScriptRuntime.setBuiltinProtoAndParent(result, scope, TopLevel.Builtins.Object);
        return result;
    }

    /**
     * Create an array with a specified initial length.
     *
     * @param scope the scope to create the object in
     * @param length the initial length (JavaScript arrays may have additional properties added
     *     dynamically).
     * @return the new array object
     */
    public static Scriptable newArray(final VarScope scope, final int length) {
        final NativeArray result = new NativeArray(length);
        ScriptRuntime.setBuiltinProtoAndParent(result, scope, TopLevel.Builtins.Array);
        return result;
    }

    /**
     * <span style="color:red">INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.</span><br>
     *
     * Create a new ArrayIterator of type NativeArrayIterator.ARRAY_ITERATOR_TYPE.KEYS
     *
     * @param scope the scope to create the object in
     * @param arrayLike the backend
     * @return the new NativeArrayIterator
     */
    public static Scriptable newArrayIteratorTypeKeys(final VarScope scope, final Scriptable arrayLike) {
        return new NativeArrayIterator(scope, arrayLike, NativeArrayIterator.ARRAY_ITERATOR_TYPE.KEYS);
    }

    /**
     * <span style="color:red">INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.</span><br>
     *
     * Create a new ArrayIterator of type NativeArrayIterator.ARRAY_ITERATOR_TYPE.VALUES
     *
     * @param scope the scope to create the object in
     * @param arrayLike the backend
     * @return the new NativeArrayIterator
     */
    public static Scriptable newArrayIteratorTypeValues(final VarScope scope, final Scriptable arrayLike) {
        return new NativeArrayIterator(scope, arrayLike, NativeArrayIterator.ARRAY_ITERATOR_TYPE.VALUES);
    }

    /**
     * <span style="color:red">INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.</span><br>
     *
     * Create a new ArrayIterator of type NativeArrayIterator.ARRAY_ITERATOR_TYPE.ENTRIES
     *
     * @param scope the scope to create the object in
     * @param arrayLike the backend
     * @return the new NativeArrayIterator
     */
    public static Scriptable newArrayIteratorTypeEntries(final VarScope scope, final Scriptable arrayLike) {
        return new NativeArrayIterator(scope, arrayLike, NativeArrayIterator.ARRAY_ITERATOR_TYPE.ENTRIES);
    }

    /**
     * Create an array with a specified initial length.
     *
     * @param scope the scope to create the object in
     * @param elements the initial elements. Each object in this array must be an acceptable
     *     JavaScript type and type of array should be exactly Object[], not SomeObjectSubclass[].
     * @return the new array object
     */
    public static Scriptable newArray(final VarScope scope, final Object[] elements) {
        if (elements.getClass().getComponentType() != ScriptRuntime.ObjectClass) {
            throw new IllegalArgumentException();
        }

        final NativeArray result = new NativeArray(elements);
        ScriptRuntime.setBuiltinProtoAndParent(result, scope, TopLevel.Builtins.Array);
        return result;
    }

    /**
     * Create an Uint8Array with a specified elements.
     *
     * @param scope the scope to create the object in
     * @param elements the initial elements..
     * @return the new Uint8Array
     */
    public static NativeUint8Array newUint8Array(final VarScope scope, final byte[] elements) {
        final NativeArrayBuffer arrayBuffer = new NativeArrayBuffer(elements.length);
        ScriptRuntime.setBuiltinProtoAndParent(arrayBuffer, scope, TopLevel.Builtins.ArrayBuffer);
        System.arraycopy(elements, 0, arrayBuffer.getBuffer(), 0, elements.length);

        final NativeUint8Array uint8Array = new NativeUint8Array(arrayBuffer, 0, elements.length);
        ScriptRuntime.setBuiltinProtoAndParent(uint8Array, scope, TopLevel.Builtins.Uint8Array);

        return uint8Array;
    }

    /**
     * @param o the object to convert
     * @return int value
     */
    public static int toInt32(final Object o) {
        return ScriptRuntime.toInt32(o);
    }

    /**
     * @param o the object to convert
     * @return double value
     */
    public static double toInteger(final Object o) {
        return ScriptRuntime.toInteger(o);
    }

    /**
     * @param args an array
     * @param index the index in the array
     * @return double value
     */
    public static double toInteger(final Object[] args, final int index) {
        return ScriptRuntime.toInteger(args, index);
    }

    /**
     * @param obj the value to check
     * @return whether obj is undefined
     */
    public static boolean isUndefined(final Object obj) {
        return org.htmlunit.corejs.javascript.Undefined.isUndefined(obj);
    }

    /**
     * @param obj the value to check
     * @return whether obj is NAN
     */
    public static boolean isNaN(final Object obj) {
        return ScriptRuntime.isNaN(obj);
    }

    /**
     * @param obj the value to check
     * @return whether obj is an Array
     */
    public static boolean isArray(final Object obj) {
        return (obj instanceof Scriptable s)
                    && "Array".equals(s.getClassName());
    }

    /**
     * @param obj the value to check
     * @return true if the passed in {@link Scriptable} looks like an array
     */
    public static boolean isArrayLike(final Scriptable obj) {
        return ScriptRuntime.isArrayLike(obj);
    }

    /**
     * @param cx the Context
     * @param obj the value to check
     * @return the length of the array like {@link Scriptable}
     */
    public static long lengthOfArrayLike(final Context cx, final Scriptable obj) {
        return AbstractEcmaObjectOperations.lengthOfArrayLike(cx, obj);
    }

    /**
     * Iterates an arrayLike {@link Scriptable} calling the {@link Consumer} on
     * every item.
     * @param cx the context or {@link Null}
     * @param arrayLike the {@link Scriptable} to iterate
     * @param consumer the {@link Consumer} to call
     */
    public static void iterateArrayLike(final Context cx, final Scriptable arrayLike, final Consumer<Object> consumer) {
        final Context context = cx == null ? Context.getCurrentContext() : cx;

        final long len = lengthOfArrayLike(context, arrayLike);
        for (int i = 0; i < len; i++) {
            final Object item = arrayLike.get(i, arrayLike);
            consumer.accept(item);
        }
    }

    /**
     * @return the top call scope
     */
    public static TopLevel getTopCallScope() {
        return ScriptRuntime.getTopCallScope(Context.getCurrentContext());
    }

    /**
     * Tries to uncompress the JavaScript code in the provided response.
     * @param scriptSource the souce
     * @param scriptName the name
     * @return the uncompressed JavaScript code
     */
    public static String uncompressJavaScript(final String scriptSource, final String scriptName) {
        final ContextFactory factory = new ContextFactory();
        final ContextAction<Object> action = cx -> {
            cx.setInterpretedMode(true);
            final Script script = cx.compileString(scriptSource, scriptName, 0, null);
            return cx.decompileScript(script, 4);
        };

        return (String) factory.call(action);
    }

    /**
     * Evaluates the <code>FindProxyForURL</code> method of the specified content.
     * @param browserVersion the browser version to use
     * @param content the JavaScript content
     * @param url the URL to be retrieved
     * @return semicolon-separated result
     */
    public static String evaluateProxyAutoConfig(final BrowserVersion browserVersion, final String content, final URL url) {
        try (Context cx = Context.enter()) {
            final ProxyAutoConfigJavaScriptConfiguration jsConfig =
                    ProxyAutoConfigJavaScriptConfiguration.getInstance(browserVersion);

            final ScriptableObject globalThis = new NativeObject();
            final TopLevel scope = cx.initSafeStandardObjects(new TopLevel(globalThis));

            for (final ClassConfiguration config : jsConfig.getAll()) {
                configureFunctions(config, scope, globalThis);
            }

            cx.evaluateString(scope, "var ProxyConfig = function() {}; ProxyConfig.bindings = {}; ProxyConfig", "<init>", 1, null);
            cx.evaluateString(scope, content, "<Proxy Auto-Config>", 1, null);

            final Object[] functionArgs = {url.toExternalForm(), url.getHost()};
            final Function f = (Function) scope.get("FindProxyForURL", scope);
            final Object result = f.call(cx, scope, globalThis, functionArgs);
            return toString(result);
        }
    }
}