# open-loop-killer

> Inject timeout protection into JavaScript loops to prevent infinite loops. Supports while, for, do-while, for-in, and for-of loops with customizable timeout and error messages.

Latest version **1.2.0** (published 2025-11-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install open-loop-killer
pnpm add open-loop-killer
yarn add open-loop-killer
bun add open-loop-killer
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2025-11-25 |
| First published | 2020-08-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 187.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | DanTe |
| Maintainers | dantemessy |
| Keywords | infinite-loop, loop-protection, timeout, code-safety, sandbox, security, ast, code-injection, untrusted-code, loop-killer, for-in, for-of, while-loop, for-loop |

## Links

- npm: https://www.npmjs.com/package/open-loop-killer
- Repository: https://github.com/dantemessy/openloopkiller
- Homepage: https://github.com/dantemessy/openloopkiller#readme
- Issues: https://github.com/dantemessy/openloopkiller/issues
- npm.io page: https://npm.io/package/open-loop-killer

## Dependencies (2)

- [esprima](https://npm.io/package/esprima.md) ^4.0.1
- [escodegen](https://npm.io/package/escodegen.md) ^2.1.0

## Alternatives

- [update-check](https://npm.io/package/update-check.md) — 4.0M weekly downloads
- [react-native-onesignal](https://npm.io/package/react-native-onesignal.md) — 134.5K weekly downloads
- [react-redux-toastr](https://npm.io/package/react-redux-toastr.md) — 33.7K weekly downloads
- [@nocobase/plugin-notification-manager](https://npm.io/package/@nocobase/plugin-notification-manager.md) — 2.0K weekly downloads
- [react-simple-toasts](https://npm.io/package/react-simple-toasts.md) — 1.9K weekly downloads

## Recent versions

- 1.2.0 (latest) — 2025-11-25
- 1.1.0 — 2025-10-30
- 1.0.4 — 2022-06-11
- 1.0.3 — 2020-08-27
- 1.0.2 — 2020-08-27
- 1.0.1 — 2020-08-27
- 1.0.0 — 2020-08-27

## README

<div align="center">
  <img src="logo.jpg" alt="Open Loop Killer Logo" width="280"/>
  
  # Open Loop Killer
  
  **Protect your JavaScript code from infinite loops**
  
  [![NPM Version][npm-image]][npm-url]
  [![NPM Downloads][downloads-image]][downloads-url]
  
  *Inject timeout protection into all loop types • Customizable • Production-ready*
</div>

---

## Install

```
npm i open-loop-killer
```

## Usage

- Runs Untrusted code securely with no open loops issue.
- Add one more layer of safety for your code.
- Protects `while`, `for`, `do-while`, `for...in`, and `for...of` loops from running indefinitely.

## How does it work

1. Parses the code to make sure it's valid JavaScript.
2. Converts it to AST (Abstract Syntax Tree).
3. Detects all loops and injects protection code.
4. Converts AST back to executable JavaScript string.

## API

### `injector(code, options)`

Injects loop protection code into JavaScript source code.

#### Parameters

- **`code`** (string, required) - The JavaScript code to protect
- **`options`** (object, optional) - Configuration options
  - **`timeout`** (number, optional) - Timeout in milliseconds before throwing error. Default: `1000`
  - **`errorMessage`** (string, optional) - Custom error message. Default: `'Open Loop Detected!'`

#### Returns

- (string) - The protected JavaScript code with injected loop protection

#### Throws

- Error if code is invalid JavaScript
- Error if options are invalid

## TypeScript Support

This package includes TypeScript type definitions out of the box. No need to install separate `@types` packages!

```typescript
import { injector, InjectorOptions } from 'open-loop-killer';

const code = 'while(true) { console.log("test"); }';
const options: InjectorOptions = {
  timeout: 2000,
  errorMessage: 'Loop timeout!'
};

const protectedCode: string = injector(code, options);
```

## Examples

### Basic Usage

```javascript
const {injector} = require('open-loop-killer');

let code = `
    while(true){
    }
`
let injectedCode = injector(code);
```

### With Custom Timeout

```javascript
const {injector} = require('open-loop-killer');

let code = `
    for(let i = 0; i < 1000000; i++){
        // Some operation
    }
`
let injectedCode = injector(code, {
    timeout: 5000  // 5 seconds
});
```

### With Custom Error Message

```javascript
const {injector} = require('open-loop-killer');

let code = `
    while(true){
    }
`
let injectedCode = injector(code, {
    errorMessage: 'Loop execution timeout exceeded!'
});
```

### With Both Options

```javascript
const {injector} = require('open-loop-killer');

let injectedCode = injector(code, {
    timeout: 2000,
    errorMessage: 'Custom timeout message'
});
```

### Injected Code Example

Input:
```javascript
while(true) { }
```

Output:
```javascript
let _a3f9b2 = Date.now();
while (true) {
    if (Date.now() - _a3f9b2 > 1000) {
        throw new Error('Open Loop Detected!');
    }
    {
    }
}
```

## Supported Loop Types

✅ **Fully Protected:**
- `while` loops
- `for` loops
- `do-while` loops
- `for...in` loops
- `for...of` loops

## Limitations

⚠️ **Important**: This package has the following limitations:

1. **No protection (not yet supported) for:**
   - ❌ `for await...of` loops (async iteration)
   - ❌ Recursive functions
   - ❌ Async loops or promises without await
   - ❌ Array methods like `.forEach()`, `.map()`, etc.

2. **Timeout behavior:**
   - Timeout is checked on each iteration
   - If a single iteration takes longer than the timeout, it won't be caught
   - Protection works best for loops with many fast iterations
   - For `for...in` and `for...of`, protection works on iteration count, not property/item count

3. **Error handling:**
   - When a loop times out, it throws an error
   - Make sure to wrap execution in try-catch if needed


## License

[MIT](./LICENSE)

[npm-image]: https://img.shields.io/npm/v/open-loop-killer.svg
[npm-url]: https://www.npmjs.com/package/open-loop-killer

[downloads-image]: https://img.shields.io/npm/dm/open-loop-killer.svg?style=flat-square
[downloads-url]: https://www.npmjs.com/package/open-loop-killer

---
_Source: https://npm.io/package/open-loop-killer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._