JsRealm Class

A realm (https://tc39.es/ecma262/#sec-code-realms): a global object, its global environment and the intrinsics.

public sealed class JsRealm

Properties

NameDescription
AbstractModuleSourceGets %AbstractModuleSource% of the realm (https://tc39.es/proposal-source-phase-imports/#sec-abstractmodulesource-objects): the abstract class that the classes of the module source objects (e.g. WebAssembly.Module) extend. It is not a global. See JsModule.ModuleSource.
EngineGets the engine (the agent) of the realm.
FunctionPrototypeGets %Function.prototype% of the realm.
GlobalObjectGets the global object ([[GlobalObject]]).
GlobalThisGets the this value of the global code ([[GlobalThisValue]] of the global environment): the global object, unless the host set another object with JsRealm.SetGlobalThis.
ObjectPrototypeGets %Object.prototype% of the realm.

AbstractModuleSource

JsRealm.Public.cs

Gets %AbstractModuleSource% of the realm (https://tc39.es/proposal-source-phase-imports/#sec-abstractmodulesource-objects): the abstract class that the classes of the module source objects (e.g. WebAssembly.Module) extend. It is not a global. See JsModule.ModuleSource.

public JsFunction AbstractModuleSource { get; }

Property value

JsFunction

Gets the engine (the agent) of the realm.

public JsEngine Engine { get; }

Property value

JsEngine

FunctionPrototype

JsRealm.Public.cs

Gets %Function.prototype% of the realm.

public JsObject FunctionPrototype { get; }

Property value

JsObject

GlobalObject

JsRealm.cs

Gets the global object ([[GlobalObject]]).

public JsObject GlobalObject { get; }

Property value

JsObject

GlobalThis

JsRealm.cs

Gets the this value of the global code ([[GlobalThisValue]] of the global environment): the global object, unless the host set another object with JsRealm.SetGlobalThis.

public JsValue GlobalThis { get; }

Property value

JsValue

ObjectPrototype

JsRealm.Public.cs

Gets %Object.prototype% of the realm.

public JsObject ObjectPrototype { get; }

Property value

JsObject

Methods

NameDescription
CreateArray(ReadOnlySpan<JsValue>)Creates an array (CreateArrayFromList).
CreateArrayBuffer(Memory<byte>, JsValue)Creates an ArrayBuffer whose data block is memory (the bytes are shared, not copied). When detachKey is not undefined, the scripts cannot detach nor transfer the buffer (e.g. the buffer of a WebAssembly.Memory); JsBinaryData.DetachArrayBuffer detaches it with the key.
CreateArrayBuffer(ReadOnlySpan<byte>)Creates an ArrayBuffer containing a copy of bytes.
CreateBufferView(JsBufferKind, JsObject, int, int)Creates a typed array or a DataView viewing buffer.
CreateBytesModule(ReadOnlySpan<byte>, string?, object?)Creates a bytes module (CreateBytesModule, the import bytes proposal): a module whose default export is a Uint8Array over an immutable ArrayBuffer that contains a copy of the bytes, imported with with { type: "bytes" }.
CreateConstructor(string, int, JsNativeConstructor)Creates a built-in function that is a constructor; its prototype property is not defined.
CreateDate(double)Creates a Date object.
CreateError(JsErrorType, string)Creates a native error of the realm, with its stack trace.
CreateException(JsErrorType, string)Creates the exception that throws a new native error of the realm.
CreateFunction(string, Action)Creates a function that calls action and returns undefined (see JsRealm.CreateFunction).
CreateFunction(string, int, JsNativeFunction)Creates a built-in function (CreateBuiltinFunction): its name and length are set; it is not a constructor.
CreateFunction(string, int, JsNativeFunction, bool)Creates a built-in function (CreateBuiltinFunction): its name and length are set; it is not a constructor.
CreateFunction<T1>(string, Action<T1>)Creates a function that calls action and returns undefined (see JsRealm.CreateFunction).
CreateFunction<TResult>(string, Func<TResult>)Creates a function that calls function: the arguments are converted with JsEngine.ToDotNet, and the result with JsRealm.FromDotNet. A conversion that fails throws a TypeError (or a RangeError) to the script; the other exceptions of the function are not JavaScript errors (throw a JsException to throw a JavaScript error).
CreateFunction<T1, T2>(string, Action<T1, T2>)Creates a function that calls action and returns undefined (see JsRealm.CreateFunction).
CreateFunction<T1, TResult>(string, Func<T1, TResult>)Creates a function that calls function: the arguments are converted with JsEngine.ToDotNet, and the result with JsRealm.FromDotNet. A conversion that fails throws a TypeError (or a RangeError) to the script; the other exceptions of the function are not JavaScript errors (throw a JsException to throw a JavaScript error).
CreateFunction<T1, T2, TResult>(string, Func<T1, T2, TResult>)Creates a function that calls function: the arguments are converted with JsEngine.ToDotNet, and the result with JsRealm.FromDotNet. A conversion that fails throws a TypeError (or a RangeError) to the script; the other exceptions of the function are not JavaScript errors (throw a JsException to throw a JavaScript error).
CreateFunction<T1, T2, T3, TResult>(string, Func<T1, T2, T3, TResult>)Creates a function that calls function: the arguments are converted with JsEngine.ToDotNet, and the result with JsRealm.FromDotNet. A conversion that fails throws a TypeError (or a RangeError) to the script; the other exceptions of the function are not JavaScript errors (throw a JsException to throw a JavaScript error).
CreateJsonModule(string, string?, object?)Creates a JSON module (ParseJSONModule): a module whose default export is the parsed JSON value.
CreateObject()Creates an ordinary object whose prototype is %Object.prototype%.
CreateObject(JsObject?)Creates an ordinary object (OrdinaryObjectCreate(proto)).
CreatePromise(Task)Creates a promise of the realm that settles when the task completes: it is fulfilled with undefined, or rejected (see JsRealm.CreatePromise).
CreatePromise(Task<JsValue>)Creates a promise of the realm that settles when the task completes (see JsRealm.CreatePromise). The value of the task must not be an object created out of the thread of the engine: use JsRealm.CreatePromise to create it when the promise settles.
CreatePromise<T>(Task<T>, Func<T, JsValue>)Creates a promise of the realm that settles when the task completes. The task can complete on any thread: the engine settles the promise on its own thread, as work posted by JsEngine.Post, so the host runs the jobs (JsEngine.RunJobs, or JsEngine.RunUntilSettledAsync). The promise is:
  • fulfilled with the result converted by convertResult, which runs on the thread of the engine (it can create objects);
  • rejected with the value of a JsException thrown by the task or by convertResult;
  • rejected with an Error whose message is the message of any other exception, or of the OperationCanceledException of a canceled task.
When the engine is disposed before the task completes, the promise stays pending.
CreateSharedArrayBuffer(JsSharedDataBlock)Creates a SharedArrayBuffer whose data is a Shared Data Block (e.g. the block of a SharedArrayBuffer of another engine).
CreateSyntheticModule(IEnumerable<string>, Action<JsSyntheticModule>, string?, object?)Creates a synthetic module whose exports are set by evaluate with JsSyntheticModule.SetExport when the module is evaluated.
CreateTextModule(string, string?, object?)Creates a text module (CreateTextModule, the import text proposal): a module whose default export is the text, imported with with { type: "text" }.
Evaluate(string)Evaluates code in this realm as an indirect eval and returns its completion value.
Execute(JsPreparedScript, object?, bool)Runs a prepared script in this realm (ScriptEvaluation) and returns its completion value.
Execute(string, string?)Runs a script in this realm (ScriptEvaluation) and returns its completion value.
FromDotNet(object?)Converts a .NET value to a JavaScript value, creating the objects in this realm:The values of the collections are converted recursively.
FromDotNet<T>(T)Converts a .NET value of type T to a JavaScript value, as JsRealm.FromDotNet does (without boxing the primitive types).
ParseModule(string, string?, object?)Parses a module (ParseModule). The module is then loaded, linked and evaluated with the methods of JsModule.
ParseModule(string, string?, object?, int, int)Parses a module (ParseModule) whose source text is a part of a document (e.g. an inline module script of an HTML document).
SetGlobalThis(JsObject)Sets the this value of the global code ([[GlobalThisValue]] of the global environment), the host-defined this value of InitializeHostDefinedRealm (https://tc39.es/ecma262/#sec-initializehostdefinedrealm): e.g. the WindowProxy of a window, whose global object is the Window. It is the this of the scripts, of the sloppy functions called without a this value and of the indirect evals, and the value of the globalThis property. Call it before any code runs in the realm.

CreateArray(ReadOnlySpan<JsValue>)

JsRealm.Public.cs

Creates an array (CreateArrayFromList).

public JsArray CreateArray(ReadOnlySpan<JsValue> items)

Parameters

items ReadOnlySpan<JsValue>

Returns

JsArray

CreateArrayBuffer overloads

CreateArrayBuffer(Memory<byte>, JsValue)

JsRealm.Public.cs

Creates an ArrayBuffer whose data block is memory (the bytes are shared, not copied). When detachKey is not undefined, the scripts cannot detach nor transfer the buffer (e.g. the buffer of a WebAssembly.Memory); JsBinaryData.DetachArrayBuffer detaches it with the key.

public JsObject CreateArrayBuffer(Memory<byte> memory, JsValue detachKey)
Parameters
memory Memory<byte>
detachKey JsValue
Returns

JsObject

CreateArrayBuffer(ReadOnlySpan<byte>)

JsRealm.Public.cs

Creates an ArrayBuffer containing a copy of bytes.

public JsObject CreateArrayBuffer(ReadOnlySpan<byte> bytes)
Parameters
bytes ReadOnlySpan<byte>
Returns

JsObject

CreateBufferView(JsBufferKind, JsObject, int, int)

JsRealm.Public.cs

Creates a typed array or a DataView viewing buffer.

public JsObject CreateBufferView(JsBufferKind kind, JsObject buffer, int byteOffset, int length)

Parameters

kind JsBufferKind
The kind of view: JsBufferKind.DataView or a typed array.
buffer JsObject
An ArrayBuffer or a SharedArrayBuffer.
byteOffset int
The offset of the view in the buffer.
length int
The number of elements (the byte length of a DataView).

Returns

JsObject

Exceptions

ArgumentException
The byte offset of a typed array is not a multiple of its element size.
ArgumentOutOfRangeException
The view does not fit in the buffer.

CreateBytesModule(ReadOnlySpan<byte>, string?, object?)

JsRealm.cs

Creates a bytes module (CreateBytesModule, the import bytes proposal): a module whose default export is a Uint8Array over an immutable ArrayBuffer that contains a copy of the bytes, imported with with { type: "bytes" }.

public JsSyntheticModule CreateBytesModule(ReadOnlySpan<byte> bytes, string? url = null, object? hostDefined = null)

Parameters

bytes ReadOnlySpan<byte>
url string?
hostDefined object?

Returns

JsSyntheticModule

Exceptions

JsException
The ArrayBuffer cannot be allocated (a RangeError).

CreateConstructor(string, int, JsNativeConstructor)

JsRealm.Public.cs

Creates a built-in function that is a constructor; its prototype property is not defined.

public JsFunction CreateConstructor(string name, int length, JsNativeConstructor constructor)

Parameters

name string
length int
constructor JsNativeConstructor

Returns

JsFunction

CreateDate(double)

JsRealm.Public.cs

Creates a Date object.

public JsObject CreateDate(double timeValue)

Parameters

timeValue double
The time value: milliseconds since the Unix epoch, or NaN for an invalid date.

Returns

JsObject

CreateError(JsErrorType, string)

JsRealm.Public.cs

Creates a native error of the realm, with its stack trace.

public JsObject CreateError(JsErrorType type, string message)

Parameters

type JsErrorType
message string

Returns

JsObject

CreateException(JsErrorType, string)

JsRealm.Public.cs

Creates the exception that throws a new native error of the realm.

public JsException CreateException(JsErrorType type, string message)

Parameters

type JsErrorType
message string

Returns

JsException

CreateFunction overloads

CreateFunction(string, Action)

JsMarshalling.cs

Creates a function that calls action and returns undefined (see JsRealm.CreateFunction).

public JsFunction CreateFunction(string name, Action action)
Parameters
name string
action Action
Returns

JsFunction

Exceptions
NotSupportedException
A type of the delegate is not supported by the conversions.

CreateFunction(string, int, JsNativeFunction)

JsRealm.Public.cs

Creates a built-in function (CreateBuiltinFunction): its name and length are set; it is not a constructor.

public JsFunction CreateFunction(string name, int length, JsNativeFunction function)
Parameters
name string
length int
function JsNativeFunction
Returns

JsFunction

CreateFunction(string, int, JsNativeFunction, bool)

JsRealm.Public.cs

Creates a built-in function (CreateBuiltinFunction): its name and length are set; it is not a constructor.

public JsFunction CreateFunction(string name, int length, JsNativeFunction function, bool runInCallerRealm)
Parameters
name string
The name of the function.
length int
The number of parameters of the function.
function JsNativeFunction
The implementation of the function.
runInCallerRealm bool
Whether the current realm while the function runs is the realm of its caller instead of the realm of the function (JsEngine.CurrentRealm, the realm of the objects created by the built-ins and the API): e.g. a function that implements an internal method of an exotic object (the traps of a proxy), which runs in the realm of the code that uses the object, or the functions of a host whose objects are created in the realm of the calling code.
Returns

JsFunction

CreateFunction<T1>(string, Action<T1>)

JsMarshalling.cs

Creates a function that calls action and returns undefined (see JsRealm.CreateFunction).

public JsFunction CreateFunction<T1>(string name, Action<T1> action)
Type parameters
T1
Parameters
name string
action Action<T1>
Returns

JsFunction

Exceptions
NotSupportedException
A type of the delegate is not supported by the conversions.

CreateFunction<TResult>(string, Func<TResult>)

JsMarshalling.cs

Creates a function that calls function: the arguments are converted with JsEngine.ToDotNet, and the result with JsRealm.FromDotNet. A conversion that fails throws a TypeError (or a RangeError) to the script; the other exceptions of the function are not JavaScript errors (throw a JsException to throw a JavaScript error).

public JsFunction CreateFunction<TResult>(string name, Func<TResult> function)
Type parameters
TResult
Parameters
name string
function Func<TResult>
Returns

JsFunction

Exceptions
NotSupportedException
A type of the delegate is not supported by the conversions.

CreateFunction<T1, T2>(string, Action<T1, T2>)

JsMarshalling.cs

Creates a function that calls action and returns undefined (see JsRealm.CreateFunction).

public JsFunction CreateFunction<T1, T2>(string name, Action<T1, T2> action)
Type parameters
T1
T2
Parameters
name string
action Action<T1, T2>
Returns

JsFunction

Exceptions
NotSupportedException
A type of the delegate is not supported by the conversions.

CreateFunction<T1, TResult>(string, Func<T1, TResult>)

JsMarshalling.cs

Creates a function that calls function: the arguments are converted with JsEngine.ToDotNet, and the result with JsRealm.FromDotNet. A conversion that fails throws a TypeError (or a RangeError) to the script; the other exceptions of the function are not JavaScript errors (throw a JsException to throw a JavaScript error).

public JsFunction CreateFunction<T1, TResult>(string name, Func<T1, TResult> function)
Type parameters
T1
TResult
Parameters
name string
function Func<T1, TResult>
Returns

JsFunction

Exceptions
NotSupportedException
A type of the delegate is not supported by the conversions.

CreateFunction<T1, T2, TResult>(string, Func<T1, T2, TResult>)

JsMarshalling.cs

Creates a function that calls function: the arguments are converted with JsEngine.ToDotNet, and the result with JsRealm.FromDotNet. A conversion that fails throws a TypeError (or a RangeError) to the script; the other exceptions of the function are not JavaScript errors (throw a JsException to throw a JavaScript error).

public JsFunction CreateFunction<T1, T2, TResult>(string name, Func<T1, T2, TResult> function)
Type parameters
T1
T2
TResult
Parameters
name string
function Func<T1, T2, TResult>
Returns

JsFunction

Exceptions
NotSupportedException
A type of the delegate is not supported by the conversions.

CreateFunction<T1, T2, T3, TResult>(string, Func<T1, T2, T3, TResult>)

JsMarshalling.cs

Creates a function that calls function: the arguments are converted with JsEngine.ToDotNet, and the result with JsRealm.FromDotNet. A conversion that fails throws a TypeError (or a RangeError) to the script; the other exceptions of the function are not JavaScript errors (throw a JsException to throw a JavaScript error).

public JsFunction CreateFunction<T1, T2, T3, TResult>(string name, Func<T1, T2, T3, TResult> function)
Type parameters
T1
T2
T3
TResult
Parameters
name string
function Func<T1, T2, T3, TResult>
Returns

JsFunction

Exceptions
NotSupportedException
A type of the delegate is not supported by the conversions.

CreateJsonModule(string, string?, object?)

JsRealm.cs

Creates a JSON module (ParseJSONModule): a module whose default export is the parsed JSON value.

public JsSyntheticModule CreateJsonModule(string json, string? url = null, object? hostDefined = null)

Parameters

json string
url string?
hostDefined object?

Returns

JsSyntheticModule

Exceptions

JsException
The text is not valid JSON (a SyntaxError).

CreateObject overloads

CreateObject()

JsRealm.Public.cs

Creates an ordinary object whose prototype is %Object.prototype%.

public JsObject CreateObject()
Returns

JsObject

CreateObject(JsObject?)

JsRealm.Public.cs

Creates an ordinary object (OrdinaryObjectCreate(proto)).

public JsObject CreateObject(JsObject? prototype)
Parameters
prototype JsObject?
The prototype, or null for an object without prototype.
Returns

JsObject

CreatePromise overloads

CreatePromise(Task)

JsEngine.Async.cs

Creates a promise of the realm that settles when the task completes: it is fulfilled with undefined, or rejected (see JsRealm.CreatePromise).

public JsObject CreatePromise(Task task)
Parameters
task Task
Returns

JsObject

CreatePromise(Task<JsValue>)

JsEngine.Async.cs

Creates a promise of the realm that settles when the task completes (see JsRealm.CreatePromise). The value of the task must not be an object created out of the thread of the engine: use JsRealm.CreatePromise to create it when the promise settles.

public JsObject CreatePromise(Task<JsValue> task)
Parameters
task Task<JsValue>
Returns

JsObject

CreatePromise<T>(Task<T>, Func<T, JsValue>)

JsEngine.Async.cs

Creates a promise of the realm that settles when the task completes. The task can complete on any thread: the engine settles the promise on its own thread, as work posted by JsEngine.Post, so the host runs the jobs (JsEngine.RunJobs, or JsEngine.RunUntilSettledAsync). The promise is:

  • fulfilled with the result converted by convertResult, which runs on the thread of the engine (it can create objects);
  • rejected with the value of a JsException thrown by the task or by convertResult;
  • rejected with an Error whose message is the message of any other exception, or of the OperationCanceledException of a canceled task.

When the engine is disposed before the task completes, the promise stays pending.

public JsObject CreatePromise<T>(Task<T> task, Func<T, JsValue> convertResult)
Type parameters
T
Parameters
task Task<T>
convertResult Func<T, JsValue>
Returns

JsObject

CreateSharedArrayBuffer(JsSharedDataBlock)

JsRealm.Public.cs

Creates a SharedArrayBuffer whose data is a Shared Data Block (e.g. the block of a SharedArrayBuffer of another engine).

public JsObject CreateSharedArrayBuffer(JsSharedDataBlock block)

Parameters

block JsSharedDataBlock

Returns

JsObject

CreateSyntheticModule(IEnumerable<string>, Action<JsSyntheticModule>, string?, object?)

JsRealm.cs

Creates a synthetic module whose exports are set by evaluate with JsSyntheticModule.SetExport when the module is evaluated.

public JsSyntheticModule CreateSyntheticModule(IEnumerable<string> exportNames, Action<JsSyntheticModule> evaluate, string? url = null, object? hostDefined = null)

Parameters

exportNames IEnumerable<string>
evaluate Action<JsSyntheticModule>
url string?
hostDefined object?

Returns

JsSyntheticModule

CreateTextModule(string, string?, object?)

JsRealm.cs

Creates a text module (CreateTextModule, the import text proposal): a module whose default export is the text, imported with with { type: "text" }.

public JsSyntheticModule CreateTextModule(string text, string? url = null, object? hostDefined = null)

Parameters

text string
url string?
hostDefined object?

Returns

JsSyntheticModule

Evaluate(string)

JsRealm.cs

Evaluates code in this realm as an indirect eval and returns its completion value.

public JsValue Evaluate(string code)

Parameters

code string

Returns

JsValue

Exceptions

JsException
The code threw an exception (a SyntaxError for invalid code).

Execute overloads

Execute(JsPreparedScript, object?, bool)

JsRealm.cs

Runs a prepared script in this realm (ScriptEvaluation) and returns its completion value.

public JsValue Execute(JsPreparedScript script, object? hostDefined = null, bool mutedErrors = false)
Parameters
script JsPreparedScript
The script.
hostDefined object?
The data of the host associated with the script ([[HostDefined]]).
mutedErrors bool
Whether the errors of the script are muted (a cross-origin script fetched without CORS).
Returns

JsValue

Exceptions
JsException
The script threw an exception.

Execute(string, string?)

JsRealm.cs

Runs a script in this realm (ScriptEvaluation) and returns its completion value.

public JsValue Execute(string code, string? url = null)
Parameters
code string
The source text of the script.
url string?
The URL (or file name) of the script, used in the stack traces and the error locations.
Returns

JsValue

Exceptions
JsException
The script threw an exception (a SyntaxError for an invalid script).

FromDotNet overloads

FromDotNet(object?)

JsMarshalling.cs

Converts a .NET value to a JavaScript value, creating the objects in this realm:

The values of the collections are converted recursively.

public JsValue FromDotNet(object? value)
Parameters
value object?
Returns

JsValue

Exceptions
NotSupportedException
The value, or a value of a collection, has a type that cannot be converted (e.g. a delegate or a class: use JsHostObject or JsRealm.CreateFunction).
InvalidOperationException
The value contains a cycle, or no engine is entered on the thread.

FromDotNet<T>(T)

JsMarshalling.cs

Converts a .NET value of type T to a JavaScript value, as JsRealm.FromDotNet does (without boxing the primitive types).

public JsValue FromDotNet<T>(T value)
Type parameters
T
Parameters
value T
Returns

JsValue

Exceptions
NotSupportedException
The value has a type that cannot be converted.
InvalidOperationException
The value contains a cycle, or no engine is entered on the thread.

ParseModule overloads

ParseModule(string, string?, object?)

JsRealm.cs

Parses a module (ParseModule). The module is then loaded, linked and evaluated with the methods of JsModule.

public JsSourceTextModule ParseModule(string code, string? url = null, object? hostDefined = null)
Parameters
code string
The source text of the module.
url string?
The URL (or file name) of the module, used to resolve its imports and in the stack traces.
hostDefined object?
The data of the host associated with the module.
Returns

JsSourceTextModule

Exceptions
JsException
The module is not valid (a SyntaxError).

ParseModule(string, string?, object?, int, int)

JsRealm.cs

Parses a module (ParseModule) whose source text is a part of a document (e.g. an inline module script of an HTML document).

public JsSourceTextModule ParseModule(string code, string? url, object? hostDefined, int lineOffset, int columnOffset)
Parameters
code string
The source text of the module.
url string?
The URL (or file name) of the module, used to resolve its imports and in the stack traces.
hostDefined object?
The data of the host associated with the module.
lineOffset int
The number of lines before the code in its document.
columnOffset int
The column of the code in the first line of its document (0-based).
Returns

JsSourceTextModule

Exceptions
JsException
The module is not valid (a SyntaxError, located at the error).

SetGlobalThis(JsObject)

JsRealm.cs

Sets the this value of the global code ([[GlobalThisValue]] of the global environment), the host-defined this value of InitializeHostDefinedRealm (https://tc39.es/ecma262/#sec-initializehostdefinedrealm): e.g. the WindowProxy of a window, whose global object is the Window. It is the this of the scripts, of the sloppy functions called without a this value and of the indirect evals, and the value of the globalThis property. Call it before any code runs in the realm.

public void SetGlobalThis(JsObject thisValue)

Parameters

thisValue JsObject
The object.