bonsai-formulas

Native Bonsai evaluation and field assignments in n8n.

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.2.0

Documentation

Bonsai for n8n

Two community nodes in one package, using Bonsai 1.4.0 locally. No shell, external calculator service, or Code-node module configuration.

Version 0.2.0. Target Elestio-instance testing is still pending. Requires Node.js 22.12+. The original unpublished 0.1 node is replaced by the two nodes below; import the updated examples rather than a 0.1 workflow.

Bonsai Evaluate

Pass Input Data and a native Expression, such as module_qty * 400. No {field} translation, fx: markers, literal guessing, type conversion, or reserved input names.

Outputs preserve the input item and add bonsai.result. Results can be numbers, text, booleans, null, arrays, or objects. Dates become ISO timestamps and durations become ISO duration strings at the n8n output boundary. Bonsai's missing-field and null behavior is preserved.

Enable Include Explanation for a bounded calculation trace under bonsai.explanation. Traces include supplied data values, so leave this off unless needed. Expression errors fail the item in either mode.

Bonsai Assign Fields

Conveniences over the same evaluator: destination/value rows, {field} references, type conversion, dependency ordering, and validation. Webhook Query Parameters is an optional input format.

Outputs preserve the input item and add formula.updates and formula.order. This node accepts scalar field results; use Evaluate for objects or lists.

Examples

Destination Value
system_size {module_qty} * 400
estimated_cost {system_size} * {account.install_rate}
review_status Ready for Review
counter ({counter} ?? 0) + 1
due_date addDays({approved_date}, 90)
review_category {system_size} > 10000 ? "Large" : "Standard"
completed_count fx:workOrders.filter(.status == "Completed").count()

Configure number/date types when Coperniq supplies strings. Supply account and workOrders as nested input data before referencing them.

Use in a workflow

  1. Fetch the current Coperniq record with an HTTP Request node.
  2. Add Bonsai Assign Fields. Set Input Fields to the clean field object, for example the project's custom object.
  3. Use Field Rows, or select Webhook Query Parameters and reference the Webhook node's query object.
  4. Inspect formula.updates in the execution output. A separate HTTP Request node can apply that object as the project's custom update after validation.

Both nodes only calculate. It does not fetch related records or write to Coperniq. Preserve the project ID separately in the workflow; query parameters should contain assignments only. Set Allowed Destinations before connecting webhook-controlled assignments to a writer.

Value rules

  • {field} reads an input or calculated value; {account.rate} reads nested supplied data.
  • {now} is the execution's current timestamp; {today} is midnight in the configured timezone (Pacific by default).
  • References make a value a formula. For expressions with no references, use fx:round(1.005,2). This prefix avoids n8n's own = expression marker. = is also accepted in webhook query values.
  • Other values are literals: 400 is numeric, true/false are booleans, and ordinary text remains text. Use fx:"00123" to preserve leading zeros.
  • References inside quoted text are not substituted. For a message use "System size: " + toString({system_size}).
  • Assignments use dependency order. {system_size} sees the newly calculated size when another assignment sets it. Self references read the stored value. {original.system_size} always reads the original normalized value. Cycles fail.
  • Missing shorthand references fail. Supply known blanks as null, then use ?? to choose a default. Native Bonsai expressions keep Bonsai's null/missing semantics; validate field names carefully.
  • A blank result fails unless Allow Null Results is enabled; fx:null then returns null. The literal text null remains text.
  • Every result is validated before updates are returned. An error yields no partial updates for that item. This does not make later API writes transactional.

Dates and types

Under Options → Field Types, add input paths or output destination fields:

  • Number: converts numeric text; rejects blanks, commas, and malformed values.
  • Boolean: accepts booleans or the exact text true/false.
  • Date Only: accepts YYYY-MM-DD, represents calendar dates at UTC midnight, and formats typed date outputs as YYYY-MM-DD. Set the type on both the source and destination for date calculations.
  • Timestamp: accepts an ISO timestamp with Z or an explicit offset. Outputs serialize as ISO timestamps.

For timestamp calendar arithmetic across DST, pass a timezone: addDays({scheduled_at}, 1, "America/Los_Angeles"). The node's timezone option controls {today}; it does not change every engine function's default timezone.

JavaScript floating-point arithmetic still applies. Use explicit rounding for displayed currency; this node is not a decimal accounting engine.

Webhook URL

Readable assignments: system_size={module_qty}*400&estimated_cost={system_size}*3.

URL-encode parameter values, especially literal + as %2B; otherwise standard query decoding turns + into a space. Repeated query parameters are rejected. Authenticate the webhook separately and pass only assignment parameters to this node.

Install and develop

An n8n owner/admin can install @adc103/n8n-nodes-bonsai-formulas@0.2.0 under Settings → Community Nodes. The n8n installer accepts a published package name; the included .tgz is for local installation/testing, not a GUI upload.

npm ci
npm run typecheck
npm test
npm pack

Source includes tests of dependency order, dates/DST, related data, URL decoding, invalid results, and the n8n node interface. The package has no Coperniq credentials, endpoints, record loading, or writes. Supply related data in the workflow. Importable examples: examples/local-preview.json and examples/native-preview.json.

Discussion