Getting Started

jshiki provides a safe and easy way to evaluate expressions. jshiki only has one lightweight dependency, acorn, which it uses parse expressions.

Getting started with jshiki is easy. First, install jshiki using your package manager of choice:

Yarn

yarn add jshiki

npm

npm install jshiki

pnpm

pnpm add jshiki

Then, get going! jshiki's API is simple:

• The parse() function takes an expression and returns a function that evaluates that expression.

  const jshiki = require('jshiki')
  
  const expression = jshiki.parse('(5 + 7) / 3')
  const result = expression()
  // result => 4
  

• The evaluate() function takes an expression and returns the result of evaluating that expression.

  const jshiki = require('jshiki')
  
  const result = jshiki.evaluate('(5 + 7) / 3')
  // result => 4
  

You can use asynchronous expressions, too!

• The parseAsync() function creates an asynchronous expression.

  const jshiki = require('jshiki')
  
  const expression = jshiki.parseAsync('(await b() + 7) / 3')
  const result = await expression({ b: async () => 5 })
  // result => 4
  

• The evaluateAsync() function evaluates an asynchronous expression.

  const jshiki = require('jshiki')
  
  const result = await jshiki.evaluateAsync('(await b() + 7) / 3', {
    scope: { b: async () => 5 }
  })
  // result => 4
  

Take a look at the type definitions to see the function signatures.

You can use all of the below in expressions:

• Booleans
• undefined, null
• Numeric literals (including BigInts, NaN, and Infinity)
• String literals (including template strings)
• Regex literals (/foo/g)
• Array literals (including sparse arrays)
• Object literals ({ prop: 'value' })
• Function calls (func())
• Member access (obj.prop)
• Optional chaining (obj?.prop?.())
• Nullish coalescing (obj ?? 'default')

---

Next, we'll look at how to let expressions access data not contained in the expression itself.