ShadowRealm

https://tc39.es/proposal-shadowrealm/
Admin
ShadowRealm is a TC39 ECMAScript proposal for creating isolated execution contexts that allow safe...
Tokens:4,826
Snippets:34
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### HostInitializeShadowRealm

Source: https://tc39.es/proposal-shadowrealm

A host-defined abstract operation used to inform the host of newly created realms from the ShadowRealm constructor, allowing for initialization of host-specific data structures.

```APIDOC
## HostInitializeShadowRealm ( realm, context, O )

### Description
This is a host-defined abstract operation that is called when a new ShadowRealm object is created. It allows the host environment to initialize any necessary host data structures related to the new realm, such as for module loading. The specification does not mandate specific additions, but Web embedding environments might include interfaces like `EventTarget`, `atob`, `TextEncoder`, etc.

### Method
Host Operation (Abstract Operation)

### Endpoint
N/A

### Parameters
- **realm** (Realm Record) - The Realm Record of the newly created realm.
- **context** (Execution Context) - The execution context associated with the realm.
- **O** (ShadowRealm object) - The newly created ShadowRealm object.

### Request Body
N/A

### Response
- **Normal Completion** or **Throw Completion** - Indicates success or failure of the initialization.

### Response Example
N/A (This is a host-level operation, not directly called by user code in the same way as prototype methods.)
```

--------------------------------

### Function.prototype.bind

Source: https://tc39.es/proposal-shadowrealm

Details the steps performed by the Function.prototype.bind method.

```APIDOC
## Function.prototype.bind ( thisArg, ...args )

### Description
This method binds a function to a given `this` value and arguments, returning a new function.

### Method
`Function.prototype.bind`

### Parameters
- **thisArg**: The value to be passed as the `this` parameter to the target function when the bound function is called.
- **args**: Optional arguments to prepend to the arguments provided to the bound function.

### Response
- Returns a new function (BoundFunction) with the `this` value and initial arguments bound.

### Notes
- Throws a TypeError if the target is not callable.
- The name and length properties of the bound function are handled to reflect its bound nature.
```

--------------------------------

### ShadowRealm Constructor

Source: https://tc39.es/proposal-shadowrealm

The ShadowRealm constructor is used to create and initialize new ShadowRealm objects. It is not intended to be called as a function.

```APIDOC
## ShadowRealm Constructor

### Description
Creates and initializes a new ShadowRealm object. This constructor is not intended to be called as a function and will throw an exception if called directly. It can be used with the `extends` clause in class definitions, requiring a `super` call to initialize the subclass instance.

### Method
Constructor

### Endpoint
N/A (JavaScript intrinsic object)

### Parameters
None directly for the constructor call itself, but `NewTarget` is used internally.

### Request Body
N/A

### Response
- **ShadowRealm Object** - A newly created ShadowRealm object.

### Response Example
```javascript
const myRealm = new ShadowRealm();
```
```

--------------------------------

### ShadowRealm API - Wrapped Function Exotic Objects

Source: https://tc39.es/proposal-shadowrealm

Explains the concept and behavior of wrapped function exotic objects within the ShadowRealm API, including their [[Call]] internal method.

```APIDOC
## ShadowRealm API - Wrapped Function Exotic Objects

### Description
A wrapped function exotic object is an exotic object that wraps a callable object. It is callable and generally results in a call of its wrapped function.

### Internal Slots
Wrapped function exotic objects do not have the internal slots of ECMAScript function objects. Instead, they have specific internal slots listed in Table 2, in addition to [[Prototype]] and [[Extensible]].

### [[Call]] ( thisArgument, argumentsList ) Internal Method

#### Description
The [[Call]] internal method of a wrapped function exotic object F executes the wrapped function, managing execution contexts.

#### Steps
1. Let callerContext be the running execution context.
2. Let calleeContext be PrepareForWrappedFunctionCall(F).
3. Assert: calleeContext is now the running execution context.
4. Let result be Completion(OrdinaryWrappedFunctionCall(F, thisArgument, argumentsList)).
5. Remove calleeContext from the execution context stack and restore callerContext as the running execution context.
6. Return ? result.

### Callable Boundary Semantics

#### Description
Host environments must ensure that if an object's identity can be observed in one realm (especially a ShadowRealm), it cannot be observed in another realm, enforcing a callable boundary.

### CreateTypeErrorCopy ( realmRecord, originalError )

#### Description
The abstract operation CreateTypeErrorCopy creates a new TypeError object within a specified realm, potentially using information from an original error.

#### Steps
1. Let newError be a newly created TypeError object.
2. NOTE: newError is created in realmRecord.
3. Return newError.

#### Host Environment Notes
Host environments may provide implementation-specific message values. The CreateTypeErrorCopy operation must not cause any ECMAScript code execution. The implementation may store additional information on originalError to produce the newError's message.
```

--------------------------------

### ShadowRealm API - Well-Known Intrinsic Objects

Source: https://tc39.es/proposal-shadowrealm

This section describes the well-known intrinsic objects associated with the ShadowRealm API, such as the ShadowRealm constructor.

```APIDOC
## ShadowRealm API - Well-Known Intrinsic Objects

### Description
This section details the well-known intrinsic objects provided by the ShadowRealm API.

### Table: Well-Known Intrinsic Objects

| Intrinsic Name | Global Name | ECMAScript Language Association |
|---|---|---|
| %ShadowRealm% | `ShadowRealm` | The ShadowRealm constructor (3.2) |
```

--------------------------------

### ShadowRealm.prototype.evaluate

Source: https://tc39.es/proposal-shadowrealm

Synchronously executes a top-level script within the ShadowRealm. The source text is interpreted as a Script and evaluated with `this` bound to the ShadowRealm's global object.

```APIDOC
## ShadowRealm.prototype.evaluate ( sourceText )

### Description
Synchronously executes a top-level script within the ShadowRealm. The `sourceText` is interpreted as a Script and evaluated with `this` bound to the ShadowRealm's global object. This is the dynamic equivalent of a `<script>` tag in HTML.

### Method
`evaluate`

### Endpoint
N/A (Method on a ShadowRealm instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **sourceText** (String) - Required - The script source code to evaluate.

### Request Example
```javascript
const myRealm = new ShadowRealm();
const result = myRealm.evaluate('1 + 2'); // result will be 3
```

### Response
#### Success Response (200)
- **Result** - The result of evaluating the script.

#### Response Example
```javascript
// Assuming the evaluated script returns a value
3
```
```

--------------------------------

### GetShadowRealmContext Operation

Source: https://tc39.es/proposal-shadowrealm

The GetShadowRealmContext abstract operation creates and returns a new execution context for a ShadowRealm.

```APIDOC
## GetShadowRealmContext ( shadowRealmRecord, strictEval )

### Description

The abstract operation GetShadowRealmContext takes arguments shadowRealmRecord (a Realm Record) and strictEval (a Boolean) and returns an ECMAScript code execution context. It sets up the environment for executing code within a ShadowRealm.

### Parameters

- **shadowRealmRecord** (Realm Record) - Required - The Realm Record representing the ShadowRealm.
- **strictEval** (Boolean) - Required - A boolean indicating whether the evaluation should be in strict mode.

### Steps

1. Create a new declarative environment for the lexical environment.
2. Set the variable environment to the ShadowRealm's global environment.
3. If `strictEval` is true, set the variable environment to the newly created lexical environment.
4. Create a new ECMAScript code execution context.
5. Set the context's Function to null.
6. Set the context's Realm to the provided `shadowRealmRecord`.
7. Set the context's ScriptOrModule to null.
8. Set the context's VariableEnvironment to the determined variable environment.
9. Set the context's LexicalEnvironment to the newly created lexical environment.
10. Set the context's PrivateEnvironment to null.
11. Return the created context.
```

--------------------------------

### PrepareForWrappedFunctionCall

Source: https://tc39.es/proposal-shadowrealm

Prepares the execution context for a wrapped function call by suspending the caller and pushing a new context onto the stack.

```APIDOC
## PrepareForWrappedFunctionCall

### Description
Sets up the execution context for a wrapped function call, ensuring the correct realm is active.

### Parameters
- **F** (wrapped function exotic object) - Required - The wrapped function being invoked.
```

--------------------------------

### ShadowRealm.prototype.importValue

Source: https://tc39.es/proposal-shadowrealm

Imports a specific named export from a module specifier into the ShadowRealm. This is equivalent to dynamic `import()` but without needing to evaluate a script source.

```APIDOC
## ShadowRealm.prototype.importValue ( specifier, exportName )

### Description
Imports a specific named export from a module `specifier` into the ShadowRealm. This is equivalent to dynamic `import()` but without needing to evaluate a script source, which can be useful when source evaluation is restricted (e.g., by CSP).

### Method
`importValue`

### Endpoint
N/A (Method on a ShadowRealm instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **specifier** (String) - Required - The module specifier (e.g., a URL or module name).
- **exportName** (String) - Required - The name of the export to import.

### Request Example
```javascript
const myRealm = new ShadowRealm();
// Assuming 'my-module' exports 'myFunction'
const myFunction = await myRealm.importValue('my-module', 'myFunction');
```

### Response
#### Success Response (200)
- **Imported Value** - The value of the requested export.

#### Response Example
```javascript
// The imported function or value
function myFunction() { /* ... */ }
```
```

--------------------------------

### CopyNameAndLength

Source: https://tc39.es/proposal-shadowrealm

Copies the 'name' and 'length' properties from a target function to a new function object, adjusting for prefixes and argument counts.

```APIDOC
## CopyNameAndLength

### Description
Utility to synchronize function metadata between a target function and a wrapper.

### Parameters
- **F** (function object) - Required - The destination function.
- **Target** (function object) - Required - The source function.
- **prefix** (String) - Optional - A prefix for the function name.
- **argCount** (Number) - Optional - The number of arguments to subtract from the length.
```

--------------------------------

### PerformShadowRealmEval

Source: https://tc39.es/proposal-shadowrealm

Details the abstract operation PerformShadowRealmEval for evaluating code within a ShadowRealm.

```APIDOC
## PerformShadowRealmEval ( sourceText, callerRealm, evalRealm )

### Description
Evaluates the given `sourceText` within the specified `evalRealm`, using `callerRealm` for error handling.

### Method
Abstract Operation

### Parameters
- **sourceText** (String): The code to evaluate.
- **callerRealm** (Realm Record): The realm of the caller, used for creating error objects.
- **evalRealm** (Realm Record): The realm in which the code will be evaluated.

### Response
- Returns a normal completion containing either a primitive value or a wrapped function exotic object.
- Returns a throw completion if an error occurs during evaluation.

### Error Handling
- Throws a SyntaxError if the parsed script contains errors, or if it contains `NewTarget`, `SuperProperty`, or `SuperCall`.
- Throws a TypeError if the evaluation result is not a normal completion or if break/continue completions are encountered (as they are not supported).

### Notes
- This operation involves parsing the `sourceText`, instantiating declarations, and evaluating the script body within the context of `evalRealm`.
- Shared logic with `eval` and `Function` is intended for future abstraction.
```

--------------------------------

### OrdinaryWrappedFunctionCall

Source: https://tc39.es/proposal-shadowrealm

Handles the execution of a wrapped function, ensuring arguments and return values are correctly wrapped across realm boundaries.

```APIDOC
## OrdinaryWrappedFunctionCall

### Description
Executes a wrapped function exotic object. It handles the wrapping of arguments for the target realm and the wrapping of the result back to the caller realm.

### Parameters
- **F** (wrapped function exotic object) - Required - The wrapped function to call.
- **thisArgument** (ECMAScript language value) - Required - The value to be used as 'this'.
- **argumentsList** (List) - Required - The list of arguments to pass to the function.
```

--------------------------------

### WrappedFunctionCreate

Source: https://tc39.es/proposal-shadowrealm

Creates a new wrapped function exotic object associated with a specific caller realm and target function.

```APIDOC
## WrappedFunctionCreate

### Description
Creates a new wrapped function exotic object. This object acts as a proxy for the target function, ensuring it operates within the correct realm context.

### Parameters
- **callerRealm** (Realm Record) - Required - The realm record associated with the caller.
- **Target** (function object) - Required - The function object to be wrapped.
```

--------------------------------

### ShadowRealmImportValue Operation

Source: https://tc39.es/proposal-shadowrealm

The abstract operation ShadowRealmImportValue handles the process of importing a specific export from a module into a ShadowRealm.

```APIDOC
## ShadowRealmImportValue ( specifierString, exportNameString, callerRealm, evalRealm )

### Description

The abstract operation ShadowRealmImportValue takes arguments specifierString (a String), exportNameString (a String), callerRealm (a Realm Record), and evalRealm (a Realm Record) and returns an ECMAScript language value. It performs the steps to load and import a module's export into a ShadowRealm.

### Parameters

- **specifierString** (String) - Required - The module specifier to import.
- **exportNameString** (String) - Required - The name of the export to import.
- **callerRealm** (Realm Record) - Required - The realm of the caller.
- **evalRealm** (Realm Record) - Required - The realm into which the module is being imported.

### Steps

1. Get the execution context for the evalRealm.
2. Create a new Promise capability.
3. Suspend the current execution context if it's not already suspended.
4. Make the evalRealm's context the running execution context.
5. Perform HostLoadImportedModule to load the module.
6. Suspend the evalRealm's context and remove it from the stack.
7. Resume the previous execution context.
8. Define steps for the onFulfilled callback (ExportGetter).
9. Define steps for the onRejected callback (ImportValueError).
10. Create a new Promise capability for the result.
11. Return the result of performing Promise.then on the imported module's promise.
```

--------------------------------

### ExportGetter Functions

Source: https://tc39.es/proposal-shadowrealm

ExportGetter functions are anonymous built-in functions used to retrieve and wrap exported values from a module.

```APIDOC
## ExportGetter functions

### Description

An ExportGetter function is an anonymous built-in function that has an [[ExportNameString]] internal slot. When called, it retrieves a specific export from a module namespace and returns its wrapped value.

### Parameters

- **exports** (module namespace exotic object) - Required - The module namespace object from which to get the export.

### Internal Slots

- **[[ExportNameString]]** (String) - The name of the export to retrieve.
- **[[Realm]]** (Realm Record) - The realm associated with the ExportGetter function.

### Steps

1. Assert that the provided `exports` is a module namespace exotic object.
2. Get the `[[ExportNameString]]` from the active function object.
3. Assert that `[[ExportNameString]]` is a String.
4. Check if the `exports` object has an own property with the name matching `[[ExportNameString]]`.
5. If not, throw a TypeError.
6. Get the value of the export from the `exports` object.
7. Get the realm from the function's `[[Realm]]` internal slot.
8. Return the wrapped value using `GetWrappedValue`.
```

--------------------------------

### ValidateShadowRealmObject Operation

Source: https://tc39.es/proposal-shadowrealm

The ValidateShadowRealmObject abstract operation ensures that a given object is a valid ShadowRealm object.

```APIDOC
## ValidateShadowRealmObject ( O )

### Description

The abstract operation ValidateShadowRealmObject takes argument O (an ECMAScript value) and returns either a normal completion containing unused or a throw completion. It validates that the provided object has the internal [[ShadowRealm]] slot.

### Parameters

- **O** (ECMAScript value) - Required - The object to validate.

### Steps

1. Perform `RequireInternalSlot(O, [[ShadowRealm]])` to ensure the object has the required internal slot.
2. Return unused (indicating success).
```

--------------------------------

### GetWrappedValue Operation

Source: https://tc39.es/proposal-shadowrealm

The GetWrappedValue abstract operation wraps a value, potentially creating a WrappedFunction exotic object if the value is a callable object.

```APIDOC
## GetWrappedValue ( callerRealm, value )

### Description

The abstract operation GetWrappedValue takes arguments callerRealm (a Realm Record) and value (an ECMAScript language value) and returns either a normal completion containing either a primitive value or a wrapped function exotic object, or a throw completion. It is used to ensure values imported into a realm are correctly handled.

### Parameters

- **callerRealm** (Realm Record) - Required - The realm of the caller.
- **value** (ECMAScript language value) - Required - The value to be wrapped or returned.

### Steps

1. Check if `value` is an Object.
2. If `value` is an Object:
   a. Check if `value` is callable using `IsCallable`.
   b. If `value` is not callable, throw a TypeError.
   c. Return the result of `WrappedFunctionCreate(callerRealm, value)`.
3. If `value` is not an Object, return `value` directly.
```

--------------------------------

### ImportValueError Functions

Source: https://tc39.es/proposal-shadowrealm

ImportValueError functions are anonymous built-in functions used to handle errors during module import.

```APIDOC
## ImportValueError functions

### Description

An ImportValueError function is an anonymous built-in function. When called with an error argument, it creates a TypeError specific to the function's associated Realm Record and throws it.

### Parameters

- **error** (any) - Required - The error to be processed.

### Internal Slots

- **Associated Realm Record** - The Realm Record associated with this ImportValueError function.

### Steps

1. Get the Realm Record associated with the function.
2. Create a copy of the provided `error` as a TypeError, specific to the Realm Record.
3. Throw the copied TypeError.
```
Tokens:
Raw