optimus.js — optimus 1.0.0-rc3

default-engines clj

Officially supported JS engines (which may or may not be available in a given runtime), in descending order of default preference. The first available engine from this list will be instantiated when make-engine is invoked without a configured preference.

error-preamble-code clj

first-available-engine clj

(first-available-engine manager engine-names)

Returns a newly instantiated javax.script.ScriptEngine for the first available engine name discoverable by the manager javax.script.ScriptEngineManager, in the given sequence engine-names, in left-to-right order of precedence. If multiple engines are available to the manager, only the first one gets instantiated. If no engines are available, nil is returned.

java8? clj

(java8?)

Returns true if the system's Java specification version is 1.8.

make-engine clj

(make-engine)

(make-engine {:keys [prefer patch-nashorn8-slice?]
              :or {prefer (or (env :optimus-js-engines) default-engines)
                   patch-nashorn8-slice? true}})

Returns a newly instantiated javax.script.ScriptEngine for the first available engine name listed in the prefer key of the map arg, which can be a comma-separated string of engine names, or a sequence of engine-name strings. If no engine preference argument is given, the default value is read from :optimus-js-engines using environ, which may be a key defined by the build tool, a Java property (java -Doptimus.js.engines=...), or a system environment variable (OPTIMUS_JS_ENGINES=...). If no environ value is given, default-engines is used. If no available engine is found for the given engine names, an exception is thrown.

The patch-nashorn8-slice? key defaults to true and causes any Nashorn engine that will be returned in a Java 8 environment, to have its Array.splice function altered to behave similarly to later Nashorn versions and other JS engines.

nashorn-array-splice-on-java8-patch-code clj

JS code altering the definition of Array.splice on Nashorn for Java 8, to match the behaviour of Array.splice on later versions of Nashorn or other JS engines.

nashorn? clj

(nashorn? engine)

Returns true if the given javax.script.ScriptEngine instance is a Nashorn script engine.

optimus-js-error clj

(optimus-js-error engine file-path error)

Returns the last Optimus JS error in engine as an instance of ExceptionInfo with line/col/path/engine properties with type ::script-error, cause error and a uniform message string (across all supported JS engines). If no Optimus JS error is found, it is assumed that some unknown exception error has occurred, so an ExceptionInfo of type ::engine-error is returned. The returned values are intended to be re-thrown by the caller after catching a script exception error (that may be lacking useful info or varies across engines).

preference-str->list clj

(preference-str->list comma-separated-engine-names)

Tokenizes a comma-separated string of engine names into a Clojure sequence of engine-name strings. Whitespace gets trimmed around each engine name and empty names get removed.

Valid inputs may look like:

"foo,baz" => ("foo", "baz")
   "foo"  => ("foo")

" bar ,," => ("bar")

run-script-with-error-handling clj

(run-script-with-error-handling engine script file-path)

Returns the result of evaluating the JS script string in engine. The result is converted to a Clojure value using clojure.java.data/from-java. Typically the JS script should be wrapped in a IIFE block to be useful. If a script exception occurs, an ExceptionInfo is thrown of either type ::script-error or ::engine-error.

with-engine clj macro

(with-engine [lname engine] & body)

Evaluates body in a try expression with lname bound to the value engine which should be a javax.script.ScriptEngine instance. The engine instance may implement java.lang.AutoCloseable (such as with GraalJS), in which case the finally clause of the try expression will attempt to close it. Note: not all JS engines implement AutoCloseable so explicit cleanup is not guaranteed for every engine.

wrap-with-error clj

(wrap-with-error script)

Wraps the given JS script string in a try/catch block that re-throws an instance of OptimusJSError (which sets up a magic variable containing error message/line/col JS Error information. JS Error info is not otherwise consistently available to the engine host Exception hierarchy, so this in-band communication channel is useful when used with run-script-with-error-handling.