kitten.sh
1<div align="center">
2 <h2 align="center" aria-label="evalish">eval<i>ish</i></h2>
3 <p align="center"><strong>A maybe slightly safer-ish wrapper around eval Function constructors</strong></p>
4 <p align="center"><i>Please maybe try something else first.. Please.</i></p>
5 <br />
6 <a href="https://npmjs.com/package/evalish">
7 <img alt="NPM Version" src="https://img.shields.io/npm/v/evalish.svg" />
8 </a>
9 <a href="https://npmjs.com/package/evalish">
10 <img alt="License" src="https://img.shields.io/npm/l/evalish.svg" />
11 </a>
12 <a href="https://bundlephobia.com/result?p=evalish">
13 <img alt="Minified gzip size" src="https://img.shields.io/bundlephobia/minzip/evalish.svg?label=gzip%20size" />
14 </a>
15 <br />
16 <br />
17</div>
18
19`evalish` is a small helper library that only exports a wrapper for the Function constructor: `SafeFunction`.
20
21The `SafeFunction` constructor allows you to evaluate code and dynamically create a new function. In most environments,
22which at least don't have their CSP configured to disallow this, this will give you a fully executable function based
23on a string. As `Function` by default is a little safer than `eval` and runs everything in the global context,
24`SafeFunction` goes a step further and attempts to isolate the environment as much as possible.
25
26It only does three simple things:
27- Isolate the [global object](https://developer.mozilla.org/en-US/docs/Glossary/Global_object) and uses a separate object using a `with` statement
28- Wraps all passed through globals, like `Array`, in a recursive masking object that disallows access to object prototype properties
29- In the browser: Creates an `iframe` element and uses that frame's globals instead to prvent prototype pollution.
30
31If you haven't run away screaming yet, maybe that's what you're looking for. Just a bit more safety.
32But really, I wrote this just for fun and I haven't written any tests yet and neither have I tested all edge cases.
33The export being named `SafeFunction` is really just ambitious.
34
35[**However, if you found a way to break out of `SafeFunction` and did something to the outside JS environment, let me
36know and file an issue.**](https://github.com/kitten/evalish/issues/new)
37I'm curious to see how far `evalish` would have to go to fully faux-isolate eval'ed code!
38
39## Usage
40
41First install `evalish` alongside `react`:
42
43```sh
44yarn add evalish
45# or
46npm install --save evalish
47```
48
49You'll then be able to import `SafeFunction` and pass it argument names and code,
50[just like the regular `Function` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/Function).
51
52```js
53import { SafeFunction } from 'evalish';
54
55new SafeFunction('a', 'b', 'return a + b')(1, 2); // returns `3`
56new SafeFunction('return window')(); // returns `undefined`
57new SafeFunction('return Array.isArray.constructor')(); // returns `undefined`
58```