steph-js v0.0.4

Steph - Ramda Style JS

Do you like Ramda style js? Me too, in fact, I kinda hate js without it. Steph is a (spicy) javascript flavor that enables such a style.

If you're wondering why that's useful I recommend reading these articles:

• Why Ramda?
• Thinking in Ramda

Ramda as a standard library

Ramda is always in scope

const takeTheGoodOneAndAddFive = pipe(prop('good'), add(5))
console.log(takeTheGoodOneAndAddFive({good: 4})) // => 9

Curried by default (Just like Steph)

const myEquals = (a, b) => a === b
const myEquals5 = myEquals(5)
console.log(myEquals5(5)) // => true
console.log(myEquals5(666)) // => false

Installation

Steph is published to npm. With yarn:

yarn add steph-js

With npm:

npm install steph-js

Command line

The following command will compile and print the js version of file-to-compile

steph file-to-compile

The compiler will add a require or import for Ramda if you use the --ramdaImport or -ri flag, it can be set to node or to es6. For example, you can pipe straight to node like so:

steph file-to-compile -ri node | node -

Specifying - as the file will read the source from stdin. For example, the following command will print 6

echo "console.log(add(5)(1))" | steph - -ri node | node -

Implementation

steph performs a babel traversal which performs the following transformations:

• Wrap function expressions and arrow functions in a call to R.curry
• Convert unbound identifiers that exist in Ramda into a R. member access

This has the following implications:

• Functions are curried by default
• Ramda acts as a sort of standard library
• Most js files that babel can compile are valid Steph. You can use your usual IDE.
• JS interop isn't handled (yet?). You can freely call Steph from js and vice-versa, but js functions will not be curried automatically.
• Classic-style function declarations are not allowed. Arrow functions are fine (() => {}) and so are function expressions function () {}. However, this will throw an error at compile time: function name() {}

Setting up a project

Using the babel plugin

First install the dependencies:

yarn add -D steph-js babel-plugin-steph-js ramda

Then add an override to your .babelrc.json:

{
  "overrides": [
    {
      "test": "**/*.steph.js",
      "plugins": [
        ["babel-plugin-steph-js", {
          "ramdaImport": "none"  // See the command line section for more import options
        }]
      ]
    }
  ]
}

Using the eslint plugin

If you're using eslint then, depending on your configuration, it might complain that the Ramda functions aren't declared. You can use eslint-plugin-ramda-env to add them your global scope. Assuming Ramda is already installed, start by installing the plugin:

yarn add -D eslint-plugin-ramda-env

In your .eslintrc.json file, add the plugin to the plugins list:

{"plugins": ["ramda-env"]}

Then use it in the overrides section:

{
    "overrides": [
        {
          "files": ["*.steph.js"],
          "env": {
            "ramda-env/ramda": true
          }
        }
      ]
}

This plugin only exports the Ramda environment, if you want actual linting, check out: https://github.com/ramda/eslint-plugin-ramda

Future steps

• Improve cli code, possibly using a library. Add standard cli features.
• Add example project that uses steph
• Consider adding literals for basic Ramda functions such as prop, path and index.
• Think of cool stuff to do with this

Acknowledgement

Thanks a lot to:

• babel - Great code, great libs and great error messages!
• Ramda - Thanks for showing me that js can be beautiful!
• @idok and @yuvalnissan - They're my bosses at wix.com and they're great! Plus, wix.com is a great company to work for, IMO.
• This project is developed using, among others:
  • node
  • yarn
  • ava
  • husky
  • eslint
  • prettier