Getting Started

Yexp has two public surfaces: an embeddable TypeScript runtime and a terminal-native JSON tool.

Use Yexp in an application

Install the core package:

npm install @cristianmartinez/yexp
# or
bun add @cristianmartinez/yexp

Compile an expression, then evaluate the reusable program against your data:

import { compile, evaluate } from '@cristianmartinez/yexp'

const affordableProducts = compile(
  '$.products.filter(product => product.price < 100)'
)

const result = evaluate(affordableProducts, {
  products: [
    { name: 'Laptop', price: 999 },
    { name: 'Mouse', price: 25 },
    { name: 'Keyboard', price: 75 }
  ]
})

console.log(result)
// [{ name: 'Mouse', price: 25 }, { name: 'Keyboard', price: 75 }]

Compiled programs are JSON-serializable and can be reused with different inputs:

const isAdult = compile('$.age >= 18')

evaluate(isAdult, { age: 21 }) // true
evaluate(isAdult, { age: 16 }) // false

Context and environment

The primary input is available through $. Auxiliary application context and environment values are explicit:

const canEdit = compile(
  '$.ownerId == $context.userId && $env.region == "eu"'
)

evaluate(canEdit, { ownerId: 'user_1' }, {
  context: { userId: 'user_1' },
  env: { region: 'eu' }
}) // true

Use Yexp in the terminal

Run the CLI once with npx:

printf '{"name":"Ada","active":true}\n' | npx @cristianmartinez/yexp-cli '.name'
# "Ada"

Or install the binary globally:

npm install --global @cristianmartinez/yexp-cli
yexp --version

Yexp reads JSON from stdin or files and writes results to stdout, so it composes with normal shell tools:

curl -s https://api.example.com/users \
  | yexp -c '.users.filter(user => user.active)' \
  | gzip > active-users.json.gz

Newline-delimited JSON is evaluated one value at a time:

printf '{"id":1}\n{"id":2}\n' | yexp -c '.id'
# 1
# 2

Useful terminal flags include:

-c for compact JSON output
-r for raw string output
-R to read input lines as strings
-s to slurp all inputs into one array
-n to evaluate once without reading input
-e to express a true/false result through the process exit status

Run yexp --help for the complete CLI contract.

Lower-level compilation pipeline

The parser and compiler are also available separately:

import { tokenize, parse, compileAst } from '@cristianmartinez/yexp'

const tokens = tokenize('$.items |> length')
const ast = parse(tokens)
const program = compileAst(ast)

Next steps

Yexp documentationEdit this page ↗