Partial application syntax and lambda parameters for JavaScript, inspired by Scala's `_` & Kotlin's `it`
npm install 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"_][blog].
> 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, ${_}!
* 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
---
_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][blog]
if you'd like to see how these can be useful.
`sh`
yarn add --dev param.macro
Make sure you also have [Babel][babel] and [babel-plugin-macros][babel-plugin-macros]
installed (the following use Babel v7, see _usage_ for more):
`sh`
yarn add --dev @babel/cli @babel/core babel-plugin-macros
... and configured with Babel:
`js`
module.exports = {
presets: [],
plugins: ['babel-plugin-macros']
}
> for usage without babel-plugin-macros, see _standalone plugin_
Then just import and use:
`js`
import { _, it } from 'param.macro'
it is also the default export, so you could also do:
`js`
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 easilyparam.macro
understandable. Anyone looking at your code will know that these symbols come from.
You can set custom identifiers for these just by using an aliased import.
`js`
import { it as IT, _ as PLACEHOLDER } from 'param.macro'
or for the default it export:
`js`
import IT from 'param.macro'
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():
`js
import it from 'param.macro'
const people = [
{ name: 'Jeff' },
{ name: 'Karen' },
{ name: 'Genevieve' }
]
people.map(it.name)
// -> ['Jeff', 'Karen', 'Genevieve']
`
Transform this:
`js
import { _ } from 'param.macro'
function sumOfThreeNumbers (x, y, z) {
return x + y + z
}
const oneAndTwoPlusOther = sumOfThreeNumbers(1, 2, _)
`
... into this:
`js
function sumOfThreeNumbers (x, y, z) {
return x + y + z
}
const oneAndTwoPlusOther = _arg => {
return sumOfThreeNumbers(1, 2, _arg)
}
`
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:
`js
import { _, it } from 'param.macro'
const identity = it
const isEqualToItself = it === it
const areSameThing = _ === _
`
... becomes:
`js
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:
`js
import { it, _ } from 'param.macro'
const hasOwn = it.hasOwnProperty(_)
const object = { flammable: true }
hasOwn(object, 'flammable')
// -> true
`
You can also put these macros to use within binary expressions, template literals,
and most other expressions.
`js
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][ramda]), which can be
pretty costly for performance.
This is a scenario specifically tested against to ensure compatibility:
`js
import { _, it } from 'param.macro'
const add = _ + _
const tenPlusString =
it
|> parseInt(_, 10)
|> add(10, _)
|> String
tenPlusString('10') |> console.log
// -> 20
`
In addition to _ and it, there is a third symbol exported by param.macro
called . 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 traverseslift
_out_ of its nearest parent function call, 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:
`js
import { _ } from 'param.macro'
const array = [1, 2, 3, 4, 5]
const sum = array.reduce(_ + _)
`
Because it produces this:
`js`
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:
`js
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.
`js`
module.exports = {
presets: [],
plugins: ['babel-plugin-macros']
}
`json`
{
"presets": [],
"plugins": ["babel-plugin-macros"]
}
A standalone version is also provided for those not already using babel-plugin-macros:
* .babelrc.js (Babel v7)
`js`
module.exports = {
presets: [],
plugins: ['module:param.macro/plugin']
}
* .babelrc (Babel v6)
`json`
{
"presets": [],
"plugins": ["param.macro/plugin"]
}
and itThere are two main & distinct constructs provided by _param.macro_:
* _ → partial application symbolit
* → implicit parameter symbol
There are a couple of major differences between the two:
_ 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:
`js
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:
`js`
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:
`js
import { _, it } from 'param.macro'
const map1 = _.map(_)
const map2 = it.map(_)
`
_However_, if nested deeper inside a function call the object placeholder _ inmap1 above would traverse further upward than an it would, and create a separate_
function _first_, before the argument placeholder inside the method call itself.lift
This creates an unary method call instead of the implicit binary function we probably
wanted, 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.
it always refers to the same argument even when used multiple times in an_
argument list. will always refer to the _next_ argument.
`js
import { _, it } from 'param.macro'
console.log(_ + _ + _)
console.log(it + it + it)
`
... are compiled to:
`js`
(_arg, _arg2, _arg3) => console.log(_arg + _arg2 + _arg3)
console.log(_it => _it + _it + _it)
> _ is a common variable name ( eg. for [lodash][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][babel-lodash] still works effectively
when you just import what you need like this:
`js`
import { add } from 'lodash'
4. Partial application with _ is damn cool
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.
* [TC39 proposal][proposal] – official syntactic proposal to the TC39 JavaScript standard
* [babel-plugin-partial-application][bppa] – precursor to this project, more features but less stable
* [lodash/fp][lodash-fp] – functional adaptation of the great Lodash utility library
* [Ramda][ramda] – highly functional programming-oriented utility library
* [babel-plugin-transform-scala-lambda][scala-lambda] – a similar plugin for more limited Scala-like lambda syntax
1. Clone the repo: git clone https://github.com/citycide/param.macro.git
2. Move into the new directory:
3. Install dependencies: or npm install
4. Build the source: or npm run build
5. Run tests: or npm test
> this project uses itself in its source, so you can use param.macro while youparam.macro
develop (_... yo dawg_)
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
4. Make sure all tests continue to pass, and it never hurts to have more tests
5. Push & pull request! :tada:
MIT © Bo Lingen / citycide
[blog]: https://medium.com/@citycide/partial-application-lambda-parameters-for-js-aa16f4d94df4
[babel]: https://babeljs.io
[babel-cli]: http://babeljs.io/docs/usage/cli/
[babel-plugin-macros]: https://github.com/kentcdodds/babel-plugin-macros
[babel-lodash]: https://github.com/lodash/babel-plugin-lodash
[proposal]: https://github.com/rbuckton/proposal-partial-application
[lodash]: https://github.com/lodash/lodash
[lodash-fp]: https://github.com/lodash/lodash/wiki/FP-Guide
[ramda]: http://ramdajs.com/
[scala-lambda]: https://github.com/xtuc/babel-plugin-transform-scala-lambda
[bppa]: https://github.com/citycide/babel-plugin-partial-application