# shadowrealm-api

**Repository Path**: ambit/shadowrealm-api

## Basic Information

- **Project Name**: shadowrealm-api
- **Description**: 🗳️ 安全的 JavaScript 沙箱，在浏览器中提供独立于全局的隔离运行时环境。依照 ShadowRealm API 提案实现，使用 TC39 Test262 的用例进行测试。
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: https://ambit-tsai.github.io/shadowrealm-api/
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 2
- **Created**: 2021-11-09
- **Last Updated**: 2024-10-14

## Categories & Tags

**Categories**: javascript-toolkits

**Tags**: 沙箱, sandbox, Realm, 沙盒

## README

# ShadowRealm API Polyfill
A implementation of the <a href="https://tc39.es/proposal-shadowrealm" target="_blank">ShadowRealm API Proposal</a>, a JavaScript sandbox, test with <a href="https://github.com/tc39/test262/tree/main/test/built-ins/ShadowRealm" target="_blank">TC39 Test262</a> cases.

[简体中文](https://gitee.com/ambit/shadowrealm-api) | English
```ts
declare class ShadowRealm {
    constructor();
    evaluate(sourceText: string): Primitive | Function;
    importValue(specifier: string, bindingName: string): Promise<Primitive | Function>;
}
```
<a href="https://ambit-tsai.github.io/shadowrealm-api/" target="_blank">Try it now 🎉</a>

## Install
```
npm i -S shadowrealm-api
```


## Usage
### Po**n**yfill: non-invasive
```javascript
import ShadowRealm from 'shadowrealm-api'

const realm = new ShadowRealm();
```

### Po**l**yfill: patch up the global object
```javascript
import 'shadowrealm-api/dist/polyfill'

const realm = new ShadowRealm();
```


## Debugging
Print internal info for debugging
```js
ShadowRealm.__debug = true;
```


## Limitations
1. All code evaluated inside a ShadowRealm runs in **strict mode**;
2. The ESM statement must not contain redundant comments;
```js
// ❌
import/* */defaultExport from "module-name";
export default/* */'xxx';

// ✅
import defaultExport from "module-name";
export default 'xxx';
```
3. Exporting variable declarations is not supported;
```js
// ❌
export const obj = {...}, fn = () => {...};

// ✅
const obj = {...}, fn = () => {...};
export { obj, fn };
```


## Compatibility
|IE|Edge|Firefox|Chrome|Safari|Opera|
|:-:|:-:|:-:|:-:|:-:|:-:|
||14|29<sup>[1][2]</sup>|32<sup>[1][2]</sup>|8<sup>[2][3]</sup>|19<sup>[1][2]</sup>|
|||41|49|10.1<sup>[3]</sup>|36|
|||||14.1||

> Notes:
> 1. Don't support destructuring assignment in ESM statement;
> 1. Need `fetch` polyfill in top window;
> 1. Need `URL` polyfill in top window;

Use polyfills:
```js
import "fetch polyfill";
import "URL polyfill";
import "shadowrealm-api/dist/polyfill";
// Your codes
```


## Contact
1. WeChat: cai_fanwei
1. QQ Group: 663286147
1. E-mail: ambit_tsai@qq.com