optimus.js — optimus 1.0.0-rc1

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.

make-engine clj

(make-engine)

(make-engine preference-list-or-str)

Returns a newly instantiated javax.script.ScriptEngine for the first available engine name listed in the preferences-list-or-str, 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.

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.