# Bonsai

> A safe, fast expression evaluator for JavaScript with pipe operators, optional chaining, and a modular plugin system.

Bonsai lets you safely evaluate expression strings in JavaScript. It's designed for data transformations, business rules, template logic, and user-facing formula editors - without the security risks of running arbitrary code.

- Package: `bonsai-js`
- ESM-only, TypeScript-first, zero runtime dependencies
- Fast compiled evaluation with cache support and benchmark regression gates

## Install

```
bun add bonsai-js
npm install bonsai-js
```

## Quick Example

```js
import { bonsai } from 'bonsai-js'
import { strings, arrays, math } from 'bonsai-js/stdlib'

const expr = bonsai()
expr.use(strings)
expr.use(arrays)
expr.use(math)

// Simple evaluation
expr.evaluateSync('2 + 3 * 4') // 14

// With context variables
expr.evaluateSync('price * quantity', { price: 9.99, quantity: 3 }) // 29.97

// Pipe operator - read as "then"
expr.evaluateSync('name |> trim |> upper', { name: '  dan  ' }) // "DAN"

// Lambda predicates for filtering
expr.evaluateSync('users |> filter(.age >= 18) |> map(.name)', {
  users: [{ name: 'Alice', age: 25 }, { name: 'Bob', age: 15 }]
}) // ["Alice"]

// Optional chaining + nullish coalescing
expr.evaluateSync('user?.profile?.avatar ?? "default.png"', { user: null }) // "default.png"

// Template literals
expr.evaluateSync('`Hello ${name}!`', { name: 'world' }) // "Hello world!"
```

## Key Features

- **Pipe operator** (`|>`): Chain transforms left-to-right for readable data pipelines
- **Optional chaining** (`?.`): Safely access nested properties without null errors
- **Nullish coalescing** (`??`): Provide fallback values for null/undefined
- **Lambda predicates**: `.age >= 18` shorthand for `item => item.age >= 18`
- **Template literals**: Backtick strings with `${expression}` interpolation
- **Safe sandbox**: Blocks prototype access, enforces timeout/depth/array limits, own-property-only context lookup, null-prototype object literals, receiver-aware method validation, sync Promise guards
- **Plugin system**: Extend with custom transforms and functions
- **Standard library**: Modular stdlib for strings, arrays, math, types, dates

## Documentation

- Full docs: [docs page](https://danfry1.github.io/bonsai-js/docs.html)
- Full docs for LLMs: [llms-full.txt](https://danfry1.github.io/bonsai-js/llms-full.txt)

## Links

- GitHub: https://github.com/danfry1/bonsai-js
- npm: https://www.npmjs.com/package/bonsai-js