Learn Bonsai

Installation #

Install Bonsai with your preferred package manager. The package is ESM-only with TypeScript types included.

Then import and start evaluating:

Common Tasks #

Start from the job you need to do. Most users do not need to read the docs from top to bottom.

Quick Start #

This is the default setup pattern for most applications: one shared instance, a small stdlib import, sync evaluation by default, and compiled rules when expressions repeat.

1. Create one instance and load what you need

Reuse this instance instead of recreating it. That keeps the cache warm and gives you one place to register custom functions or safety settings.

2. Pass data in through the context object

3. Use pipes for readable transformations

The pipe operator reads left to right. It is the simplest way to express cleanup, filtering, mapping, and formatting work.

4. Compile expressions that repeat

Mental Model #

You only need four ideas to work effectively with Bonsai.

Literals & Types #

Literals are the values you can write directly inside an expression. Everything else comes from the context object, property access, functions, or transforms.

Operators #

Operators cover math, comparison, branching, and membership tests. The rules are close to JavaScript, but == is strict in Bonsai - there is no loose equality.

Arithmetic

Comparison & equality

Conditional logic

Use ?? for nullish defaults, || for falsy defaults, and the ternary operator when you need an explicit if/else branch.

Membership

in and not in work with arrays and strings. They are a good fit for tags, roles, lists, and substring checks.

Property Access #

Use property access to read nested objects, array elements, and dynamic keys from the context object. Missing values resolve to undefined, which makes ?? defaults very natural.

Dot & bracket notation

Optional chaining

Use ?. when you want to say, directly in the expression, that a missing branch is expected and should quietly produce undefined.

Pipe Operator #

Pipes are how you build readable data flow. They take a value on the left and pass it into a transform on the right, which makes cleanup and collection logic much easier to scan.

Basic pipe

|> passes the left-hand value as the first argument to the transform on the right.

Chaining

Each stage receives the previous result, so the expression reads in the same order as the transformation itself.

Pipes with arguments

The piped value is always the first argument. Any extra arguments go in parentheses after the transform name. When there are no extra arguments, parentheses are optional — name |> trim and name |> trim() are identical.

Complex pipelines

Most real application rules end up looking like this: filter a collection, project the values you care about, then format the result.

Collections #

Collections let you build structured results directly inside an expression. Use them when the result should be data, not just a boolean or string.

Array literals

Object literals

Method calls

Core method-call support is intentionally small. Bonsai allows a safe subset of built-in string, array, and number methods such as slice, includes, startsWith, repeat, trimStart, at, and toFixed.

Template Literals #

Template literals are for building display strings: messages, labels, emails, filenames, and user-facing output.

Lambda Predicates #

Lambdas are Bonsai's shorthand for “do this to each item” inside array transforms like map, filter, find, some, and every.

Property extraction

A dot prefix like .name means “read this property from each item”. You do not declare a parameter name; the current array item is implied.

Predicate filtering

Add a condition after the accessor when you want a boolean test for each item.

Compound lambdas

Lambdas support nested property access, logic operators, and the same safe method-call surface available elsewhere in the language.

bonsai(options?) #

Create one configured evaluator instance and reuse it anywhere you need expression execution, validation, or compiled rules.

Choose the right API

Options

Blocked names like __proto__, constructor, and prototype are always denied. If you want to allow user.name, you must allow both user and name.

Common setups

evaluateSync & evaluate #

Use the sync path by default. Switch to the async path only when a registered transform or function may return a promise.

Signatures

Both methods treat the context object as the variable scope for the expression. There is no global scope and no hidden runtime state.

evaluateSync(expression, context?)

Evaluate immediately and return the result. The context is a plain object whose properties become identifiers in the expression.

evaluate(expression, context?)

Return a promise and await async extensions during evaluation.

Typed generics

Both entrypoints accept an optional generic for result typing:

compile & validate #

Use compile() for repeated execution and validate() before you store or accept user-authored expressions.

compile(expression)

Compile once and keep the returned CompiledExpression around for repeated execution.

Compiled expressions stay associated with the instance that created them, so they continue to use that instance's safety settings and currently registered transforms/functions.

validate(expression)

Parse without executing. This is useful for editors, validation UIs, and preflight checks before persisting an expression.

references lists the identifiers, transforms, and functions mentioned in the expression. validate() does not execute the expression and does not verify that those transforms/functions are currently registered.

Extending #

Extend Bonsai with your own transforms, functions, and plugins when you need domain-specific behavior.

Transforms

Transforms are used with |> and receive the piped value as their first argument.

Functions

Functions are called directly by name in the expression.

Plugins

Registering the same name again replaces the previous implementation. Transforms and functions live in separate registries, so the same name can exist once in each namespace.

Instance Methods #

Inspect the registry, remove extensions, and clear caches without rebuilding the entire instance.

evaluateExpression #

A convenience helper for one-off evaluations backed by a shared default instance.

This helper is good for scripts, tests, and one-off evaluations. It uses one shared default instance behind the scenes, so it is intentionally minimal: no custom safety options, no custom plugins, and no lifecycle control.

Error Handling #

Match on exported error classes and security codes instead of parsing message text.

Runtime error classes

Evaluation-time errors carry a location when the runtime can attach one, plus a preformatted formatted message for direct display. Parse errors expose source, start, and end directly.

formatError(message, location, suggestion?) / formatBonsaiError(error)

Security error codes

BonsaiSecurityError uses a code property to identify the type of violation:

Catching errors

Strings #

Load the string stdlib when you need text cleanup, normalization, search, and formatting inside pipelines.

Common patterns:

Arrays #

Load the array stdlib when your expressions need collection work: counting, searching, projection, deduping, and simple aggregation.

Basic transforms

sort sorts numbers numerically and falls back to string comparison for other values.

Higher-order transforms

These accept lambda predicates as arguments for filtering, mapping, and searching.

Practical examples:

Math #

Load the math stdlib for rounding, clamping, and summarizing numeric values in pipelines.

Transforms

Functions

Common patterns:

Types #

Load the types stdlib when the input shape is mixed and you need defensive checks or simple conversions.

Type checks are useful when the same field may arrive in different shapes:

Dates #

Load the dates stdlib when you need current timestamps, UTC formatting, or day differences between timestamps.

All date transforms work with Unix timestamps in milliseconds. formatDate() uses UTC components, not local time-zone formatting.

Format patterns: YYYY (year), MM (month), DD (day), HH (hours), mm (minutes), ss (seconds).

All (bundle) #

Load every standard library module at once - for quick prototyping or when you want everything available.

Writing Plugins #

Plugins are the packaging layer for your expression API. Use them to ship a cohesive set of transforms and functions for one domain.

Plugin structure

A plugin is a function that receives a Bonsai instance and registers whatever that domain needs.

Registering plugins

Apply plugins during setup, not in the middle of request handling. That keeps the instance predictable and the caches warm.

Real-world example: currency plugin

Here is a practical plugin for formatting and calculating prices:

Safety & Sandboxing #

Bonsai constrains the expression language. It is suitable for safe expression evaluation, but your own registered extensions still run as normal host JavaScript.

What Bonsai blocks by default

Expressions cannot access the global scope, import modules, or reach dangerous prototype properties.

Property restrictions

allowedProperties and deniedProperties apply to member access (obj.name) and method calls (str.slice()), not root identifiers (name) or object-literal keys ({ name: value }). Numeric array indices (e.g., items[0]) bypass allow/deny lists automatically.

If you want to permit user.name, you must allow both user and name as member names. Root identifiers like user in evaluateSync('user.name', { user }) are always accessible -the allow/deny lists only restrict what comes after the dot. Use an allowlist for user-authored expressions whenever possible.

Defense-in-depth hardening

Beyond the configurable property restrictions, Bonsai applies several layers of protection automatically:

Recommended deployment profiles

Resource limits

Protect against resource exhaustion with timeout, maxDepth, and maxArrayLength.

What Bonsai does not do

Performance #

The fastest path is a reused instance, compiled hot-path expressions, and sync execution when your extensions do not need promises.

Recommended usage

Benchmarks #

Measured with vitest bench on Apple Silicon (M-series). Treat these as point-in-time guidance, not part of the API contract.

vs Jexl

Run benchmarks yourself: bunx vitest bench

Why it's fast

• Per-instance caches - repeated expressions reuse parsed ASTs and compiled expression objects.
• Compiler optimizations - Constant folding and dead branch elimination at compile time.
• Zero dependencies - no runtime dependency graph to initialize or ship.
• Hand-written parser - Recursive descent, no parser generators or regex-heavy tokenizers.

Optimization tips

Use compile() for repeated expressions. If the same expression runs in a loop or on every request, compile it once and reuse the compiled object. This skips parsing and optimization entirely.

Use evaluateSync over evaluate. The sync path avoids Promise overhead. Only use evaluate when you have async transforms.

Choose an appropriate cache size. The default (256) works well for most applications. If you have thousands of unique expression strings, increase it. If memory is tight, decrease it.