Skip to content

Latest commit

 

History

History
459 lines (274 loc) · 14.9 KB

quickjsvm.md

File metadata and controls

459 lines (274 loc) · 14.9 KB

quickjs-emscripten › Globals › QuickJSVm

Class: QuickJSVm

QuickJSVm wraps a QuickJS Javascript runtime (JSRuntime*) and context (JSContext*). This class's methods return QuickJSHandle, which wrap C pointers (JSValue*). It's the caller's responsibility to call .dispose() on any handles you create to free memory once you're done with the handle.

Each QuickJSVm instance is isolated. You cannot share handles between different QuickJSVm instances. You should create separate QuickJSVm instances for untrusted code from different souces for isolation.

Use QuickJS.createVm to create a new QuickJSVm.

Create QuickJS values with methods like newNumber, newString, newObject, and newFunction.

Call setProp or defineProp to customize objects. Use those methods with global to expose the values you create to the interior of the interpreter, so they can be used in evalCode.

Hierarchy

  • QuickJSVm

Implements

Index

Constructors

Accessors

Methods

Constructors

constructor

+ new QuickJSVm(args: object): QuickJSVm

Defined in quickjs.ts:144

Use QuickJS.createVm to create a QuickJSVm instance.

Parameters:

Name Type
args object

Returns: QuickJSVm

Accessors

global

• get global(): QuickJSHandle

Defined in quickjs.ts:179

global. A handle to the global object inside the interpreter. You can set properties to create global variables.

Returns: QuickJSHandle

undefined

• get undefined(): QuickJSHandle

Defined in quickjs.ts:164

undefined.

Returns: QuickJSHandle

Methods

callFunction

▸ callFunction(func: QuickJSHandle, thisVal: QuickJSHandle, ...args: QuickJSHandle[]): VmCallResult‹QuickJSHandle›

Defined in quickjs.ts:375

func.call(thisVal, ...args). Call a JSValue as a function.

See unwrapResult, which will throw if the function returned an error, or return the result handle directly.

Parameters:

Name Type
func QuickJSHandle
thisVal QuickJSHandle
...args QuickJSHandle[]

Returns: VmCallResult‹QuickJSHandle›

A result. If the function threw, result error be a handle to the exception.

defineProp

▸ defineProp(handle: QuickJSHandle, key: string | QuickJSHandle, descriptor: VmPropertyDescriptor‹QuickJSHandle›): void

Defined in quickjs.ts:329

Object.defineProperty(handle, key, descriptor).

Parameters:

Name Type Description
handle QuickJSHandle -
key string | QuickJSHandle The property may be specified as a JSValue handle, or as a Javascript string (which will be converted automatically).
descriptor VmPropertyDescriptor‹QuickJSHandle› -

Returns: void

dispose

▸ dispose(): void

Defined in quickjs.ts:506

Dispose of this VM's underlying resources.

throws Calling this method without disposing of all created handles will result in an error.

Returns: void

dump

▸ dump(handle: QuickJSHandle): any

Defined in quickjs.ts:431

Dump a JSValue to Javascript in a best-effort fashion. Returns handle.toString() if it cannot be serialized to JSON.

Parameters:

Name Type
handle QuickJSHandle

Returns: any

evalCode

▸ evalCode(code: string): VmCallResult‹QuickJSHandle›

Implementation of LowLevelJavascriptVm

Defined in quickjs.ts:415

Like eval(code). Evauatetes the Javascript source code in the global scope of this VM.

See unwrapResult, which will throw if the function returned an error, or return the result handle directly.

Note: to protect against infinite loops, provide an interrupt handler to setShouldInterruptHandler. You can use shouldInterruptAfterDeadline to create a time-based deadline.

Parameters:

Name Type
code string

Returns: VmCallResult‹QuickJSHandle›

The last statement's value. If the code threw, result error will be a handle to the exception. If execution was interrupted, the error will have name InternalError and message interrupted.

getNumber

▸ getNumber(handle: QuickJSHandle): number

Defined in quickjs.ts:220

Converts handle into a Javascript number.

Parameters:

Name Type
handle QuickJSHandle

Returns: number

NaN on error, othewise a number.

getProp

▸ getProp(handle: QuickJSHandle, key: string | QuickJSHandle): QuickJSHandle

Defined in quickjs.ts:287

handle[key]. Get a property from a JSValue.

Parameters:

Name Type Description
handle QuickJSHandle -
key string | QuickJSHandle The property may be specified as a JSValue handle, or as a Javascript string (which will be converted automatically).

Returns: QuickJSHandle

getString

▸ getString(handle: QuickJSHandle): string

Defined in quickjs.ts:235

Converts handle to a Javascript string.

Parameters:

Name Type
handle QuickJSHandle

Returns: string

newFunction

▸ newFunction(name: string, fn: VmFunctionImplementation‹QuickJSHandle›): QuickJSHandle

Implementation of LowLevelJavascriptVm

Defined in quickjs.ts:264

Convert a Javascript function into a QuickJS function value. See VmFunctionImplementation for more details.

A VmFunctionImplementation should not free its arguments or its retun value. A VmFunctionImplementation should also not retain any references to its veturn value.

Parameters:

Name Type
name string
fn VmFunctionImplementation‹QuickJSHandle›

Returns: QuickJSHandle

newNumber

▸ newNumber(num: number): QuickJSHandle

Implementation of LowLevelJavascriptVm

Defined in quickjs.ts:212

Converts a Javascript number into a QuckJS value.

Parameters:

Name Type
num number

Returns: QuickJSHandle

newObject

▸ newObject(prototype?: QuickJSHandle): QuickJSHandle

Implementation of LowLevelJavascriptVm

Defined in quickjs.ts:246

{}. Create a new QuickJS object.

Parameters:

Name Type Description
prototype? QuickJSHandle Like Object.create.

Returns: QuickJSHandle

newString

▸ newString(str: string): QuickJSHandle

Implementation of LowLevelJavascriptVm

Defined in quickjs.ts:228

Create a QuickJS string value.

Parameters:

Name Type
str string

Returns: QuickJSHandle

removeShouldInterruptHandler

▸ removeShouldInterruptHandler(): void

Defined in quickjs.ts:493

Remove the interrupt handler, if any. See setShouldInterruptHandler.

Returns: void

setProp

▸ setProp(handle: QuickJSHandle, key: string | QuickJSHandle, value: QuickJSHandle): void

Defined in quickjs.ts:311

handle[key] = value. Set a property on a JSValue.

remarks Note that the QuickJS authors recommend using defineProp to define new properties.

Parameters:

Name Type Description
handle QuickJSHandle -
key string | QuickJSHandle The property may be specified as a JSValue handle, or as a Javascript string (which will be converted automatically).
value QuickJSHandle -

Returns: void

setShouldInterruptHandler

▸ setShouldInterruptHandler(cb: ShouldInterruptHandler): void

Defined in quickjs.ts:481

Set a callback which is regularly called by the QuickJS engine when it is executing code. This callback can be used to implement an execution timeout.

The interrupt handler can be removed with removeShouldInterruptHandler.

Parameters:

Name Type
cb ShouldInterruptHandler

Returns: void

typeof

▸ typeof(handle: QuickJSHandle): string

Defined in quickjs.ts:204

typeof operator. Not standards compliant.

remarks Does not support BigInt values correctly.

Parameters:

Name Type
handle QuickJSHandle

Returns: string

unwrapResult

▸ unwrapResult(result: VmCallResult‹QuickJSHandle›): QuickJSHandle

Defined in quickjs.ts:454

Unwrap a VmCallResult, returning it's value on success, and throwing the dumped error on failure.

Parameters:

Name Type
result VmCallResult‹QuickJSHandle›

Returns: QuickJSHandle