readme.md

param.macro ·

Partial application syntax and lambda parameters for JavaScript, inspired by Scala's _ & Kotlin's it. Read more about this macro in the intro blog post "Partial Application & Lambda Parameter Syntax for JavaScript".

try it live on the online playground

• overview
• installation
  • set custom tokens
• examples & features
  • lambda parameters: utensilList.find(it.isFork())
  • argument placeholders: add(1, _)
  • in assignments: const areSameThing = _ === _
  • other expressions: it.getPower().level > 9000, const greet = `Hello, ${_}!`
  • lift modifier: ;[1, 2].reduce(lift(_ + _))
• usage
  • Babel v7
  • Babel v6
  • standalone plugin
• differences between _ and it
• caveats & limitations
• comparison to libraries
• see also
• development
• contributing
• license

---

overview

param.macro provides two main symbols — it and _.

it can be used in an expression passed to a function which implicitly creates a lambda function in place accepting a single argument.

The _ symbol is inspired by Scala and is used as a placeholder to signal that a function call is partially applied — the original code isn't actually called yet, but will return a new function receiving the arguments you signified as placeholders. Think of the values that aren't placeholders as being "bound", and you'll provide the rest later.

Check out the examples section and the official introduction post if you'd like to see how these can be useful.

installation

yarn add --dev param.macro

Make sure you also have Babel and babel-plugin-macros installed (the following use Babel v7, see usage for more):

yarn add --dev @babel/cli @babel/core babel-plugin-macros

... and configured with Babel:

module.exports = {
  presets: [],
  plugins: ['babel-plugin-macros']
}

for usage without babel-plugin-macros, see standalone plugin

Then just import and use:

import { _, it } from 'param.macro'

it is also the default export, so you could also do:

import it from 'param.macro'

The benefits of this explicit import are that linters and type systems won't have a fit over _ and it not being defined. It's also self-documenting and more easily understandable. Anyone looking at your code will know that these symbols come from param.macro.

set custom tokens

You can set custom identifiers for these just by using an aliased import.

import { it as IT, _ as PLACEHOLDER } from 'param.macro'

or for the default it export:

import IT from 'param.macro'

examples

lambda parameters

Scala, Kotlin, etc have what's called a lambda parameter — an easy shorthand for passing unary (single-argument) functions to other functions (higher order). It's useful in higher order functions like Array#map():

import it from 'param.macro'

const people = [
  { name: 'Jeff' },
  { name: 'Karen' },
  { name: 'Genevieve' }
]

people.map(it.name)
// -> ['Jeff', 'Karen', 'Genevieve']

argument placeholders

Transform this:

import { _ } from 'param.macro'

function sumOfThreeNumbers (x, y, z) {
  return x + y + z
}

const oneAndTwoPlusOther = sumOfThreeNumbers(1, 2, _)

... into this:

function sumOfThreeNumbers (x, y, z) {
  return x + y + z
}

const oneAndTwoPlusOther = _arg => {
  return sumOfThreeNumbers(1, 2, _arg)
}

_ and it in assignments

Most expressions using _ and it can also be used outside function calls and assigned to a variable. Here are some ultra simple cases to demonstrate this:

import { _, it } from 'param.macro'

const identity = it
const isEqualToItself = it === it

const areSameThing = _ === _

... becomes:

const identity = _it => _it
const isEqualToItself = _it2 => _it2 === _it2

const areSameThing = (_arg, _arg2) => _arg === _arg2

We could implement a hasOwn() function to check if a property exists on an object like this:

import { it, _ } from 'param.macro'

const hasOwn = it.hasOwnProperty(_)
const object = { flammable: true }

hasOwn(object, 'flammable')
// -> true

other expressions

You can also put these macros to use within binary expressions, template literals, and most other expressions.

import { it, _ } from 'param.macro'

const log = console.log(_)

log([0, 1, 0, 1].filter(!!it))
// -> [1, 1]

const heroes = [
  { name: 'bob', getPower () { return { level: 9001 } } },
  { name: 'joe', getPower () { return { level: 4500 } } }
]

log(heroes.find(it.getPower().level > 9000))
// -> { name: 'bob', getPower: [Function] }

const greet = `Hello, ${_}!`

log(greet('world'))
// -> Hello, world!

It's especially fun to use with the pipeline operator since it basically removes the need to auto-curry an entire library's API (like Ramda), which can be pretty costly for performance.

This is a scenario specifically tested against to ensure compatibility:

import { _, it } from 'param.macro'

const add = _ + _
const tenPlusString =
  it
  |> parseInt(_, 10)
  |> add(10, _)
  |> String

tenPlusString('10') |> console.log
// -> 20

lift modifier

In addition to _ and it, there is a third symbol exported by param.macro called lift. In most scenarios it is simply removed from the output but is very useful in combination with _ placeholders.

Because it creates only unary functions in place and _ always traverses out of its nearest parent function call, lift serves as an operator that fills out the middle ground: using placeholders to create inline functions of any arity.

With _ alone, the following example will not do what you probably want:

import { _ } from 'param.macro'

const array = [1, 2, 3, 4, 5]
const sum = array.reduce(_ + _)

Because it produces this:

const array = [1, 2, 3, 4, 5]
const sum = (_arg, _arg2) => {
  return array.reduce(_arg + _arg2)
}

To actually pass in an implicit binary function with _ you can use the lift operator:

import { _, lift } from 'param.macro'

const array = [1, 2, 3, 4, 5]
const sum = array.reduce(lift(_ + _))
console.log(sum)
// -> 15

It may be helpful to note that _ is still following its own rules here: it traversed upward out of its parent function call! It just so happens that call is removed afterward leaving your new function exactly where you want it.

usage

.babelrc.js (Babel v7)

module.exports = {
  presets: [],
  plugins: ['babel-plugin-macros']
}

.babelrc (Babel v6)

{
  "presets": [],
  "plugins": ["babel-plugin-macros"]
}

standalone plugin

A standalone version is also provided for those not already using babel-plugin-macros:

• .babelrc.js (Babel v7)

  module.exports = {
    presets: [],
    plugins: ['module:param.macro/plugin']
  }

• .babelrc (Babel v6)

  {
    "presets": [],
    "plugins": ["param.macro/plugin"]
  }

differences between _ and it

There are two main & distinct constructs provided by param.macro:

• _ → partial application symbol
• it → implicit parameter symbol

There are a couple of major differences between the two:

scoping

_ will always traverse upward out of the nearest function call, while it will be transformed in place. It's easiest to see when we look at a simple example:

import { _, it } from 'param.macro'

const array = [1, 2, 3]
array.map(_)
array.map(it)

While these look like they might be the same, they'll come out acting very different:

const array = [1, 2, 3]
_arg => array.map(_arg)
array.map(_it => _it)

An exception to these scoping differences is at the top-level, like the right-hand side of an assignment. it and _ behave similarly here since there's no further upward to go, so they'll both happen to target the same place.

For example the following two map implementations do the same thing:

import { _, it } from 'param.macro'

const map1 = _.map(_)
const map2 = it.map(_)

However, if nested deeper inside a function call the object placeholder _ in map1 above would traverse further upward than an it would, and create a separate function first, before the argument placeholder _ inside the method call itself. This creates an unary method call instead of the implicit binary function we probably wanted, lift or not.

The it implementation in map2 above does still create the implicit binary function, even if nested deeper. And following the normal placeholder rules, any _ inside the method call will traverse up to the method call and stop to create a function there, as we wanted.

argument reuse

it always refers to the same argument even when used multiple times in an argument list. _ will always refer to the next argument.

import { _, it } from 'param.macro'

console.log(_ + _ + _)
console.log(it + it + it)

... are compiled to:

(_arg, _arg2, _arg3) => console.log(_arg + _arg2 + _arg3)
console.log(_it => _it + _it + _it)

caveats & limitations

_ is a common variable name ( eg. for lodash )

This is the most obvious potential pitfall when using this plugin. _ is commonly used as the identifier for things like lodash's collection of utilities.

There are a few reasons this is totally fine.

1. The plugin allows for custom symbols

   If you do happen to need _ or it as identifiers, you're able to change the imported symbols (using standard aliased imports) to anything you want.

2. _ is a common symbol for partial application

   The Scala language uses the underscore as a placeholder for partially applied functions, and tons of JavaScript libraries have also used it — so it's become recognizable.

3. Monolithic builds of packages like lodash are on the way out

   lodash v5 will be getting rid of the monolithic build in favor of explicitly imported or 'cherry-picked' utilities. So it will become less common to see the entirety of lodash imported, especially with ES module tree-shaking on the horizon.

   On top of that, babel-plugin-lodash still works effectively when you just import what you need like this:

   import { add } from 'lodash'

4. Partial application with _ is damn cool

comparison to libraries

Lodash, Underscore, Ramda, and other libraries have provided partial application with a helper function something like _.partial(fn, _) which wraps the provided function, and basically just takes advantage of the fact that {} !== {} to recognize that the monolithic _, _.partial.placeholder, or Ramda's R.__ is a specific object deemed a placeholder.

This Babel plugin gives you the same features at the syntax level. And on top of that, it adds features no runtime library can manage (like arbitrary expressions) and comes with zero runtime overhead. The macros are compiled away and turn into regular functions that don't have to check their arguments to see if a placeholder was provided.

see also

• TC39 proposal – official syntactic proposal to the TC39 JavaScript standard
• babel-plugin-partial-application – precursor to this project, more features but less stable
• lodash/fp – functional adaptation of the great Lodash utility library
• Ramda – highly functional programming-oriented utility library
• babel-plugin-transform-scala-lambda – a similar plugin for more limited Scala-like lambda syntax

development

1. Clone the repo: git clone https://github.com/citycide/param.macro.git
2. Move into the new directory: cd param.macro
3. Install dependencies: yarn or npm install
4. Build the source: yarn build or npm run build
5. Run tests: yarn test or npm test

this project uses itself in its source, so you can use param.macro while you develop param.macro (... yo dawg)

contributing

Pull requests and any issues found are always welcome.

1. Fork the project, and preferably create a branch named something like feat-make-better
2. Follow the build steps above but using your forked repo
3. Modify the source files in the src directory as needed
4. Make sure all tests continue to pass, and it never hurts to have more tests
5. Push & pull request! 🎉

license

MIT © Bo Lingen / haltcase