What is Bonsai

Bonsai is a small, safe, typed expression language for JavaScript applications. It evaluates text such as

user.plan == "pro" && orders.filter(.paid).map(.total).sum() > 100 // => true

against data you pass in, without executing JavaScript. It is meant for logic that people other than your developers write: pricing and eligibility rules, saved filters, formula fields, notification templates, and feature conditions.

Throughout this site, // => value after an expression shows its result, and the host is your application: the data it passes in (the context) and the functions it adds (host functions).

Common tasks

Task	Where
Save a rule written by a user, safely	A hardened setup
Show why a rule passed or failed	Reasons
Autocomplete and diagnostics in an editor	Editor Support
Add Bonsai to a CodeMirror editor	CodeMirror
Run a filter in SQL or MongoDB	Database Filters
Add your own function	Host Functions
Handle errors	Errors
Set limits for untrusted input	Limits
Upgrade from 0.x	Migrating from 0.x
Build feature flag targeting	Recipe: Feature Flag Targeting
Let users filter a table in SQL	Recipe: User-Defined Filters in SQL
Explain eligibility decisions	Recipe: Eligibility Rules with Reasons

What you get

• Familiar syntax. JavaScript operators and names: a.b, ?., ??, template literals, filter, map, includes, toUpperCase. Every function also works as a method, so sum(xs) and xs.sum() are the same call.
• Static checking. Declare the shape of your data once with t and get errors for typos, wrong types, and possibly-null values before an expression is saved, with suggestions and exact source ranges. The TypeScript types of the context and the result are inferred from the same declaration.
• Safety by construction. No globals, no prototype access, no calling functions found in data, no conversion hooks, no mutation. Every evaluation terminates and is bounded by a step budget, size limits, an optional timeout, and an AbortSignal.
• Speed. Expressions compile once to closures (no eval, safe under a strict Content Security Policy) and are cached per environment.
• Editor support. A language service in bonsai-js/service provides completions, hover, and diagnostics without evaluating anything.
• No dependencies. Runs in Node.js 22 and newer, current Bun, and modern ESM browsers.

What it is not

Bonsai is not a general-purpose language. There are no loops, no recursion, no assignment, and no user-defined functions beyond lambdas passed to built-ins. That is deliberate: it is what makes every expression terminate and keeps the checker precise. When an expression needs something the language does not have, you add a host function.

Where to go next

• Install and follow the Quick Start.
• Read the Mental Model: the handful of rules that differ from JavaScript.
• Browse the language reference and the built-in functions.
• Try expressions in the Playground.
• Choosing a library? See how Bonsai compares with others, including where another library is the better fit.
• Upgrading? See Migrating from 0.x.