https://github.com/alii/scraggy
Portable JS interpreter, built for avoiding eval() under strict CSP in the browser
https://github.com/alii/scraggy
interpreter js parser vm
Last synced: about 1 month ago
JSON representation
Portable JS interpreter, built for avoiding eval() under strict CSP in the browser
- Host: GitHub
- URL: https://github.com/alii/scraggy
- Owner: alii
- Created: 2025-03-08T16:47:02.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-09T17:41:31.000Z (over 1 year ago)
- Last Synced: 2026-05-05T20:46:48.303Z (about 2 months ago)
- Topics: interpreter, js, parser, vm
- Language: TypeScript
- Homepage: https://npmjs.com/package/scraggy
- Size: 323 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
Scraggy
A relatively safe JavaScript code evaluator that doesn't use `eval()` or `Function()`. This library parses and executes JavaScript code using an AST-based approach.
[](https://github.com/alii/scraggy/actions/workflows/bun-test.yml)
## Features
- Evaluates JavaScript code without using the built-in `eval()` or `Function()` constructor
- Supports a subset of common JavaScript language features
- Provides proper memory management and cleanup
- Uses Acorn for parsing JavaScript into an AST
## Installation
```bash
bun install scraggy
```
## Usage
```typescript
import {evaluate} from 'scraggy';
// Simple evaluation with an empty context
const result = await evaluate({}, '2 + 3'); // returns 5 (basic arithmetic works with no globals)
// Evaluation with a context object
const context = {x: 10, y: 20};
const result = await evaluate(context, 'x + y'); // returns 30
// More complex evaluations - no globals needed
const code = `
function factorial(n) {
if (n <= 1) return 1;
return n * factorial(n - 1);
}
factorial(5)
`;
const result = await evaluate({}, code); // returns 120
```
## Supported Features
- Literals (numbers, strings, booleans, null, undefined)
- Variables and scope handling (although there's no difference between var, const, let). There is also no hoisting
- Object and array literals
- Object property access (both dot notation and bracket notation)
- Array element access
- Function declarations and function expressions
- Arrow functions
- Rest parameters and spread operators
- Binary expressions (+, -, \*, /, %, etc.)
- Logical expressions (&&, ||, ??)
- Unary expressions (+, -, !, ~, typeof)
- if/else statements
- while loops
- for loops (for, for...in, for...of)
- try/catch/finally blocks
- async/await with Promises
- switch statements
- Class declarations and class expressions with inheritance
- Destructuring assignments (object and array)
- Super references in class methods
- Destructuring in function parameters
- Template literals with expression interpolation
- Optional chaining (?.)
## Security Features
This evaluator is designed with security in mind:
- **No Default Globals**: Unlike JavaScript's `eval()`, this evaluator does not provide ANY built-in global objects by default. This means features like `Promise`, `setTimeout`, `console` are not available unless you explicitly provide them.
- **Explicit Context**: You must explicitly provide any global objects that your code needs through the context parameter, giving you fine-grained control over what's accessible.
- **Sandboxed Execution**: The evaluator cannot access the host environment outside what you provide in the context.
## Limitations and Unsupported Features
To avoid running into unexpected issues, be aware of the following unsupported features:
### Unsupported Syntax
- Module import/export statements
- Private fields (#property)
- Generator functions and yield
- BigInt literals
- Default values in destructuring assignments
### Partially Supported
- Regular expression literals (should be provided via global context)
- Object method definitions use function expressions under the hood
- Only basic error handling is implemented
- Built-in objects like Promise, Error, Math, JSON, Date, etc. must be explicitly provided in the global context if needed
- Nullish coalescing (??) is supported in binary expressions
### Runtime Environment
- No DOM or Web API support
- Limited global object
- No access to Node.js or Bun built-in modules
## Development
To run tests:
```bash
bun test
```
To typecheck:
```bash
bun tsc --noEmit
```
## License
MIT