stunsail ·

Super opinionated, functional utility collection.

installation

# using yarn:
yarn add stunsail
# or npm:
npm i stunsail

usage

import S from 'stunsail'
// commonjs / ES5
const S = require('stunsail')

A module version is also available if you use ES modules:

import S from 'stunsail/es'

You can also selectively import just what you need, which is especially recommended if you use the babel plugin as this is much more efficient.

import { defaults, kebabCase, matches, toArray } from 'stunsail'
const { defaults, kebabCase, matches, toArray } = require('stunsail')

api

See the documentation here for a more complete reference.

overview

import {
  clamp,
  map,
  filter,
  first,
  matches,
  pipe,
  toNumber
} from 'stunsail'
const number = pipe(
  '36',
  num => toNumber(num),      // -> 36
  num => clamp(num, 10, 30), // -> 30
  num => console.log(num)    // -> 'number = 30'
)
const found = pipe(
  map([1, 2, 3, 4, 5], num => ({ value: num * 2 })),
  // -> [{ value: 2 }, { value: 4 }, ... ]
  objects => filter(objects, obj => matches(obj, { value: 6 })),
  // -> [{ value: 6 }]
  objects => first(objects),
  // -> { value: 6 }
  obj => console.log(obj.value)
  // -> 6
)

with param.macro

stunsail is really fun to use alongside param.macro — a Babel plugin that lets you partially apply functions at compile time. You can make the above example look like this:

import { _, it } from 'param.macro'
import {
  clamp,
  map,
  filter,
  first,
  matches,
  pipe,
  toNumber
} from 'stunsail'
const number = pipe(
  '36',
  toNumber(_),
  clamp(_, 10, 30),
  console.log(`number = ${_}`)
)
const found = pipe(
  map([1, 2, 3, 4, 5], { value: it * 2 }),
  filter(_, matches(_, { value: 6 })),
  first(_),
  console.log(_.value)
)

This combo allows you to use stunsail like you would lodash/fp or Ramda, but without the runtime performance hit that comes with an auto-curried library.

babel plugin

stunsail ships with a babel plugin included. It can be used like so:

babel v7

.babelrc.js →

module.exports = {
  presets: [],
  plugins: ['module:stunsail/babel']
}

babel v6

.babelrc →

{
  "presets": [],
  "plugins": ["stunsail/babel"]
}

This will allow you to write simpler imports but output and still benefit from more efficient alternatives, ie:

import { partition } from 'stunsail'
// commonjs / ES5
const { partition } = require('stunsail')

... will be compiled to:

import partition from 'stunsail/partition'
// commonjs / ES5
const partition = require('stunsail/partition')

import statements can optionally be compiled to equivalent require calls to avoid adding a module transformer separately.

configuration

Optionally configure the plugin by using an Array of [pluginName, optionsObject]:

module.exports = {
  presets: [],
  plugins: [
    ['module:stunsail/babel', {
      useRequire: false,
      useModules: true
    }]
  ]
}

property	type	default	description
useRequire	Boolean	false	Whether to convert import statements to requires. Has no effect on require calls.
useModules	Boolean	false	Redirect stunsail imports to stunsail/es. Ignored if useRequire is set to true.

see also

• param.macro – Babel plugin for compile-time partial application and lambda parameters
• tryad – Monadic mashup of Maybe & Either (Option/Result) for more functional null & error handling

contributing

Search the issues if you come across any trouble, open a new one if it hasn't been posted, or, if you're able, open a pull request. Contributions of any kind are welcome in this project.

license

MIT © Bo Lingen / citycide