Swift script-host API

This appendix is for engine integrators embedding the QuickJS wrapper. These are Swift APIs, not JavaScript globals. Public signatures are extracted from ScriptVM.swift. Private conversion/interrupt helpers are intentionally excluded. Keep a VM and its values on one thread.

ScriptException.file

public let file: String

Source filename carried by the exception.

ScriptException.line

public let line: Int

Source line, or 0 when the VM could not recover it.

ScriptException.message

public let message: String

Human-readable error message.

ScriptException.kind

public var kind: Kind = .error

Classification: error, timeout, outOfMemory, or stackOverflow.

ScriptException.init

public init(file: String, line: Int, message: String, kind: Kind = .error)

Makes a script error the host reports itself (file, line, message; kind defaults to an error), the same shape the VM gives for a thrown JavaScript error.

ScriptVM.exceptionHandler

public var exceptionHandler: ((ScriptException) -> Void)?

Optional closure receiving reported ScriptException values. Set it before evaluating code when you need diagnostics.

ScriptVM.timeoutHandler

public var timeoutHandler: (() -> Void)?

Optional closure invoked when the VM time budget is exceeded. It is not a JavaScript timer.

ScriptVM.interruptHandler

public var interruptHandler: (() -> Bool)?

An optional host check QuickJS polls every few thousand operations, even with no call budget: return true to stop the running script with an uncatchable "interrupted" (a cancel button, a deadline).

ScriptVM.exceptionSourceURL

public var exceptionSourceURL: String?

Prefer this source file's stack frame when reporting an error: for languages built on the VM whose native wrappers throw from inside a prelude, so the error points at the user's line.

ScriptVM.callBudget

public var callBudget: Double = 0.05

Top-level JavaScript CPU-time budget in seconds. Default 0.05. Nested calls share it; native Swift work is excluded. 0 disables this host-side limit.

ScriptVM.activeBudget

public private(set) var activeBudget: Double = 0

Read-only budget for the current/last guarded call, in seconds.

ScriptVM.memoryLimit

public var memoryLimit: Int = 256 << 20

Runtime-wide QuickJS allocation limit in bytes, not a per-entity limit. Default 256 MiB. Non-positive values are passed as zero to QuickJS; do not use zero as an unlimited-memory setting.

ScriptVM.maxStackSize

public var maxStackSize: Int = 512 << 10
public var maxStackSize: Int = 640 << 10
public var maxStackSize: Int = 4 << 20

Native stack limit in bytes. Default 640 KiB on Windows and 4 MiB elsewhere. Non-positive values are passed as zero to QuickJS. Exhaustion is reported as a script error.

ScriptVM.init

public init()

Creates a QuickJS runtime and context with the configured defaults. Keep each VM confined to one thread.

ScriptVM.evaluate

public func evaluate(_ source: String, file: String) -> ScriptValue?

source is JavaScript text; file supplies the diagnostic filename. Evaluates it as a global script and returns its value, or nil after an exception is reported.

ScriptVM.syntaxError

public func syntaxError(in source: String, file: String) -> ScriptException?

Compiles source with the supplied file name without executing it. Returns a ScriptException for invalid syntax, otherwise nil.

ScriptVM.global

public var global: ScriptValue

Returns a ScriptValue for the global object.

ScriptVM.subscript

public subscript(name: String) -> ScriptValue

name is a global property key. Returns a ScriptValue, including an undefined value for an absent property.

ScriptVM.set

public func set(_ name: String, _ value: Any?)

name is a global property key; value is converted from Swift and assigned to it. Returns nothing.

ScriptVM.define

public func define(_ name: String, _ body: @escaping ([ScriptValue]) -> Any?)

name is a global native-function name; body receives an array of ScriptValue arguments and returns a Swift value to convert back to JavaScript. Returning nil becomes JavaScript null. Returns nothing.

ScriptVM.budgeted

public func budgeted<T>(_ body: () -> T) -> T

Runs several host operations (property reads, calls, conversions) under one shared time budget, so a script that hides work in getters can't get a fresh budget for each property. Inside a running call it shares that call's budget.

ScriptVM.make

public func make(_ value: Any?) -> ScriptValue

value is a supported Swift value. Returns its ScriptValue representation. Unsupported Swift types become undefined.

ScriptVM.copyCutShort

public private(set) var copyCutShort = false

True when the last copy into Swift ran past its budget (the values past it became null). A host that needs the whole value refuses it instead of using a list cut short.

ScriptVM.copyLimit

public var copyLimit = ScriptVM.copyBudget

This VM's copy budget: 100,000 values for a game script, more where a host passes whole data sets through (the Forge's meshes). Past it values become null and copyCutShort is set; the memory limit still caps everything.

ScriptValue.isUndefined

public var isUndefined: Bool

Tests whether the wrapped JavaScript value is undefined.

ScriptValue.isNull

public var isNull: Bool

Tests whether the wrapped value is null.

ScriptValue.isObject

public var isObject: Bool

Tests the native object tag. Check isArray/isFunction separately when those distinctions matter.

ScriptValue.isArray

public var isArray: Bool

Tests whether the value is a JavaScript array.

ScriptValue.isFunction

public var isFunction: Bool

Tests whether the value is callable in its VM context.

ScriptValue.isNumber

public var isNumber: Bool

Tests the numeric tag; it does not itself validate finiteness.

ScriptValue.isString

public var isString: Bool

True when the value is a JavaScript string (no conversion).

ScriptValue.isBoolean

public var isBoolean: Bool

True when the value is a JavaScript boolean (no conversion).

ScriptValue.coercedString

public var coercedString: String?

The ECMAScript String() of the value, including "null" and "undefined"; nil only if the conversion itself throws.

ScriptValue.int32

public var int32: Int32

ECMAScript ToInt32: wraps modulo 2^32, unlike a checked Swift integer conversion.

ScriptValue.subscript

public subscript(name: String) -> ScriptValue

name is a JavaScript property key. Returns a wrapped property value.

ScriptValue.set

public func set(_ name: String, _ v: Any?)

name is the property key; v is the Swift value to convert and assign. Returns nothing.

ScriptValue.call

public func call(_ args: [Any?] = []) -> ScriptValue?

args is a list of Swift values, default empty. Calls the function with undefined as this. Returns a ScriptValue, or nil after an exception is reported.

ScriptValue.toSwift

public var toSwift: Any?

Converts back to Swift: null/undefined become nil; ordinary numbers become Double; arrays and objects are copied with bounded depth/size. Callable values can remain ScriptValue wrappers.

ScriptValue.toSwiftWhole

public var toSwiftWhole: Any?

Like toSwift, but nil when the value is bigger than the VM's copy budget: never a copy cut short.

ScriptValue.string

public var string: String?

Returns nil for null/undefined, otherwise asks QuickJS for string conversion.

ScriptValue.double

public var double: Double

Asks QuickJS for numeric conversion; callers must still validate the result.

ScriptValue.int

public var int: Int

Converts the numeric value by truncating toward zero. Unrepresentable/invalid values become 0.

ScriptValue.bool

public var bool: Bool

Uses JavaScript truthiness, not only literal true/false.

ScriptValue.doubles

public var doubles: [Double]

Returns numeric array elements, up to the conversion limit; a non-array returns an empty array.

ScriptValue.array

public var array: [Any]

Returns a converted Swift array or an empty array when conversion is not an array.

Arguments.arg

func arg(_ i: Int) -> ScriptValue?

i is a non-negative zero-based argument index. Returns the argument or nil when i is at/above count. A negative index is not protected; do not supply one.

Arguments.double

func double(_ i: Int) -> Double

i is a non-negative argument index. Returns numeric conversion, or 0 when absent.

Arguments.u32

func u32(_ i: Int) -> UInt32

i is a non-negative argument index. Returns an exactly representable UInt32, otherwise 0; fractions, negatives and out-of-range values do not wrap.

Arguments.int

func int(_ i: Int) -> Int

i is a non-negative argument index. Returns truncating Int conversion, or 0 when absent/invalid.

Arguments.optionalID

func optionalID(_ i: Int) -> UInt32?

An entity id that may be absent: a whole number from 0 to UInt32.max, else nil (-1, null, 3.7, 1e100 and NaN all mean none). Never clamped or truncated onto another object.

Arguments.itemCount

func itemCount(_ i: Int) -> Int

A count (items, amounts): whole numbers cut toward zero, bounded to plus or minus one billion; NaN, infinities and huge numbers give 0.

Arguments.string

func string(_ i: Int) -> String

i is a non-negative argument index. Returns string conversion, or an empty string when absent/null/undefined.

Arguments.bool

func bool(_ i: Int) -> Bool

i is a non-negative argument index. Returns JavaScript truthiness, or false when absent.

Arguments.doubles

func doubles(_ i: Int) -> [Double]

i is a non-negative argument index. Returns a numeric array, or an empty array when absent/not an array.

Conversion notes

Swift nil/NSNull becomes JavaScript null. Supported scalars, arrays and string-keyed dictionaries are converted recursively. Integers become JavaScript numbers, so large 64-bit integers are not guaranteed exact. Unsupported Swift types become undefined. JavaScript-to-Swift copies are bounded (100,000 values, 32 levels), and are not a substitute for a checked save format. Those copy guards are not used by Swift-to-JavaScript conversion through make; validate the size and nesting of host input separately. JavaScript null and undefined both convert to Swift nil.