Benoît

0.8.0 verified Fri May 01 auth: no javascript

Benoît is a self-interpreting, self-evolving, self-proving programming language where every line is simultaneously code, test, proof, and documentation. Version 0.8.0 runs .ben files natively via a Pratt parser and tree-walking evaluator (zero eval, zero new Function), offers 68% token reduction compared to equivalent JavaScript, and includes a genetic algorithm (evolve.mjs) that discovers functions from assertions alone with 80% success rate. Active development with monthly releases, it targets Node >=18 and focuses on human-AI collaboration, pattern matching with guards, pipes, async/await, and a built-in property inference engine that detects 31 mathematical properties automatically. Unlike traditional languages, there is no separation between code, tests, and documentation.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported ↓

cause Package is ESM-only since v0.4.0; using require() in a CJS context.

fix

Use dynamic import or switch to ESM: import benoit from 'benoit'.

error TypeError: benoit.compile is not a function ↓

cause compile was renamed to transpile in v0.5.0.

fix

Use import { transpile } from 'benoit' instead.

error SyntaxError: Unexpected token (0:22) - '?' is not valid at this position ↓

cause Using '?' as a condition marker in a pattern without proper alt branch syntax.

fix

Ensure guard '?' follows the pattern arrow correctly: pattern -> guard? -> expr.

error Error: runBen expects a string or a file path, got object ↓

cause runBen requires a string of code or a .ben file path.

fix

Call runBen with a string or a path, not an options object.

Warnings

breaking v0.4.0 dropped CommonJS support; package is ESM-only. ↓

fix Use import syntax instead of require(). Update Node to >=12 and set "type": "module" in package.json.

breaking v0.5.0 renamed compile API to transpile. ↓

fix Replace compile with transpile in imports. compile is no longer exported.

breaking v0.6.0 changed default export from a parse function to a multi-purpose transformer. ↓

fix If using default import, adjust usage to new shape. Use named exports for specific operations.

deprecated evalBen function deprecated since v0.7.0; use runBen instead. ↓

fix Replace evalBen with runBen. evalBen remains for backward compatibility but will be removed in next major.

gotcha Pattern-matching guards use 'when' keyword; 'if' is not valid inside patterns. ↓

fix Use 'when condition ->' inside alt patterns, not 'if condition ->'.

gotcha Token-reduction measurement is for transpiled JS, not for performance; no benchmarks guarantee speed improvement. ↓

fix Do not assume Benoît code runs faster; it is a syntactic compaction tool.

Install

npm install benoit

yarn add benoit

pnpm add benoit

Imports

default
wrong
```
const benoit = require('benoit')
```
correct
```
import benoit from 'benoit'
```
ESM-only since v0.4.0. Default export is the transpiler/interpreter function.
runBen
wrong
```
import { run_ben } from 'benoit'
```
correct
```
import { runBen } from 'benoit'
```
Function to run .ben strings or files. Exported as runBen (camelCase), not run_ben.
transpile
wrong
```
import { compile } from 'benoit'
```
correct
```
import { transpile } from 'benoit'
```
Transpiles Benoît code to JavaScript. compile was removed in v0.5.0.
EvolveMachine
wrong
```
import { evolve } from 'benoit'
```
correct
```
import { EvolveMachine } from 'benoit'
```
Class for the self-programming machine. evolve is a CLI script (evolve.mjs), not a library export.

Quickstart

Shows how to run Benoît code inline via runBen, verifying assertions directly from a string. The language ships with full TypeScript definitions.

import { runBen } from 'benoit';

const code = `
fib n ->
  n < 2? -> n
  else? -> fib(n - 1) + fib(n - 2)

fib(0) is 0
fib(5) is 5
fib(10) is 55
`;

runBen(code).then(({ passed, total }) => {
  console.log(`Passed ${passed}/${total} assertions.`);
}).catch(err => console.error(err));