sh-syntax

README

sh-syntax

A WASM shell parser and formatter with bash support, based on mvdan/sh

TOC

• Usage
  • Install
  • API
• Benchmark
• Sponsors
• Backers
• Changelog
• License

Usage

Install

# yarn
yarn add sh-syntax

# npm
npm i sh-syntax

API

// node
import { parse, print } from 'sh-syntax'

const text = "echo 'Hello World!'"
const ast = await parse(text)
const newText = await print(ast, {
  // `originalText` is required for now, hope we will find better solution later
  originalText: text,
})

// browser
import { getProcessor } from 'sh-syntax'

const processor = getProcessor(() =>
  fetch('sh-syntax/main.wasm').then(res => res.arrayBuffer()),
)

const parse = (text, options) => processor(text, options)

const print = (textOrAst, options) => {
  if (typeof textOrAst === 'string') {
    return processor(textOrAst, {
      ...options,
      print: true,
    })
  }
  return processor(textOrAst, options)
}

// just like node again
const text = "echo 'Hello World!'"
const ast = await parse(text)
const newText = await print(ast, { originalText: text })

Benchmark

clk: ~3.10 GHz
cpu: Apple M1 Max
runtime: node 18.20.8 (arm64-darwin)

benchmark                   avg (min … max) p75 / p99    (min … top 1%)
------------------------------------------- -------------------------------
sh-syntax                     36.97 ms/iter  37.32 ms     █
                      (36.50 ms … 37.53 ms)  37.38 ms █   █              ██
                    (601.05 kb … 711.16 kb) 641.13 kb █▁▁██▁▁▁█▁▁██▁█▁▁▁▁██
                  4.88 ipc (  0.63% stalls)  99.64% L1 data cache
        118.27M cycles 577.63M instructions  38.24% retired LD/ST (220.90M)

sh-syntax (synckit)           37.13 ms/iter  37.04 ms      █
                      (36.69 ms … 38.15 ms)  38.05 ms ▅ ▅  █
                    (291.31 kb …   4.70 mb) 553.03 kb █▇█▇▇█▁▇▁▁▁▁▁▁▁▁▇▁▁▁▇
                  1.04 ipc ( 11.15% stalls)  38.89% L1 data cache
        406.85k cycles 423.12k instructions  20.01% retired LD/ST ( 84.65k)

mvdan-sh                      78.00 ms/iter  74.63 ms     █
                     (70.44 ms … 127.50 ms)  78.25 ms     █  █
                    (  1.11 mb …   9.87 mb)   7.88 mb █▁▁▁█▁▁██▁███▁▁▁▁▁▁▁█
                  5.18 ipc (  1.02% stalls)  99.05% L1 data cache
        244.60M cycles   1.27G instructions  34.47% retired LD/ST (436.51M)

summary
  sh-syntax
   1x faster than sh-syntax (synckit)
   2.11x faster than mvdan-sh

See benchmark for more details.

You can try it with running node benchmark by yourself. Here is the benchmark source code.

Sponsors

1stG	RxTS	UnTS

Backers

1stG	RxTS	UnTS

Changelog

Detailed changes for each release are documented in CHANGELOG.md.

License

MIT © JounQin@1stG.me