Common FP

Functional programming for the commoner

What Is It?#

An opinionated utility library with a few goals

• Utilities are built with multiple data types in mind
• Functional without the jargon
• Friendly errors

Get Started#

1. Install
   .sh

   npm i common-fp
   
   # using typescript?
   npm i common-fp-types

2. And use
   .js.ts

   Try It

   import { mapValues } from 'common-fp'
   
   const giveEveryoneAnApple = mapValues(numApples => numApples + 1)
   
   const applesPerPersonObj = {
     jason: 2,
     amy: 3,
   }
   
   const resultObj = giveEveryoneAnApple(applesPerPersonObj)
   console.log(resultObj)
   // a new object {
   //   jason: 3,
   //   amy: 4,
   // }
   import { mapValues } from 'common-fp'
   
   const giveEveryoneAnApple = mapValues((numApples: number) => numApples + 1)
   
   const applesPerPersonObj = {
     jason: 2,
     amy: 3,
   }
   
   const resultObj = giveEveryoneAnApple(applesPerPersonObj)
   console.log(resultObj)
   // a new object {
   //   jason: 3,
   //   amy: 4,
   // }
   

   .js.ts

   Try It

   import { mapValues } from 'common-fp'
   
   const giveEveryoneAnApple = mapValues(
     numApples => numApples + 1
   )
   
   const applesPerPersonObj = {
     jason: 2,
     amy: 3,
   }
   
   const resultObj = giveEveryoneAnApple(
     applesPerPersonObj
   )
   console.log(resultObj)
   // a new object {
   //   jason: 3,
   //   amy: 4,
   // }
   import { mapValues } from 'common-fp'
   
   const giveEveryoneAnApple = mapValues(
     (numApples: number) => numApples + 1
   )
   
   const applesPerPersonObj = {
     jason: 2,
     amy: 3,
   }
   
   const resultObj = giveEveryoneAnApple(
     applesPerPersonObj
   )
   console.log(resultObj)
   // a new object {
   //   jason: 3,
   //   amy: 4,
   // }
   

   You can also pass a Map
   .js.ts

   Try It

   const applesPerPersonMap = new Map([
     ['jason', 2],
     ['amy', 3],
   ])
   
   const resultMap = giveEveryoneAnApple(applesPerPersonMap)
   console.log(resultMap)
   // a new Map [
   //   ['jason', 3],
   //   ['amy', 4],
   // ]
   const applesPerPersonMap = new Map([
     ['jason', 2],
     ['amy', 3],
   ])
   
   const resultMap = giveEveryoneAnApple(applesPerPersonMap)
   console.log(resultMap)
   // a new Map [
   //   ['jason', 3],
   //   ['amy', 4],
   // ]
   

   .js.ts

   Try It

   const applesPerPersonMap = new Map([
     ['jason', 2],
     ['amy', 3],
   ])
   
   const resultMap = giveEveryoneAnApple(
     applesPerPersonMap
   )
   console.log(resultMap)
   // a new Map [
   //   ['jason', 3],
   //   ['amy', 4],
   // ]
   const applesPerPersonMap = new Map([
     ['jason', 2],
     ['amy', 3],
   ])
   
   const resultMap = giveEveryoneAnApple(
     applesPerPersonMap
   )
   console.log(resultMap)
   // a new Map [
   //   ['jason', 3],
   //   ['amy', 4],
   // ]
   

   mapValues works with arrays and Sets as well
   .js.ts

   Try It

   const capitalize = str => str[0].toUpperCase() + str.slice(1)
   const capitalizeAll = mapValues(capitalize)
   
   const peopleArr = ['kim', 'grace']
   const resultArr = capitalizeAll(peopleArr)
   console.log(resultArr)
   // a new array [
   //   'Kim',
   //   'Grace',
   // ]
   
   const peopleSet = new Set(['kim', 'grace'])
   const resultSet = capitalizeAll(peopleSet)
   console.log(resultSet)
   // a new Set [
   //   'Kim',
   //   'Grace',
   // ]
   const capitalize = (str: string) => str[0].toUpperCase() + str.slice(1)
   const capitalizeAll = mapValues(capitalize)
   
   const peopleArr = ['kim', 'grace']
   const resultArr = capitalizeAll(peopleArr)
   console.log(resultArr)
   // a new array [
   //   'Kim',
   //   'Grace',
   // ]
   
   const peopleSet = new Set(['kim', 'grace'])
   const resultSet = capitalizeAll(peopleSet)
   console.log(resultSet)
   // a new Set [
   //   'Kim',
   //   'Grace',
   // ]
   

   .js.ts

   Try It

   const capitalize = str =>
     str[0].toUpperCase() + str.slice(1)
   const capitalizeAll = mapValues(capitalize)
   
   const peopleArr = ['kim', 'grace']
   const resultArr = capitalizeAll(peopleArr)
   console.log(resultArr)
   // a new array [
   //   'Kim',
   //   'Grace',
   // ]
   
   const peopleSet = new Set(['kim', 'grace'])
   const resultSet = capitalizeAll(peopleSet)
   console.log(resultSet)
   // a new Set [
   //   'Kim',
   //   'Grace',
   // ]
   const capitalize = (str: string) =>
     str[0].toUpperCase() + str.slice(1)
   const capitalizeAll = mapValues(capitalize)
   
   const peopleArr = ['kim', 'grace']
   const resultArr = capitalizeAll(peopleArr)
   console.log(resultArr)
   // a new array [
   //   'Kim',
   //   'Grace',
   // ]
   
   const peopleSet = new Set(['kim', 'grace'])
   const resultSet = capitalizeAll(peopleSet)
   console.log(resultSet)
   // a new Set [
   //   'Kim',
   //   'Grace',
   // ]
   

Why Build It?#

I wanted a utility library that worked with data types generically. Years ago I built a crude personal version I really liked. Common FP is a refined and expanded version that hopefully others find helpful.

Who Is This For?#

Common FP is for people who

• Want utilities that work with data types generically.

  For example, mapValues allows us to map over the values of an array, object, Map, or Set and return a new instance of the data type passed in.
• Are interested in some functional concepts...

  ...but not interested in diving in the deep end.

  Helpful concepts like immutability are common in JavaScript and can be used without currying, knowing what an "identity function" is, or learning any theory. Those things may be useful for people wanting to learn them but pose a barrier for those who don't.

• Have run into limitations with chaining.

  Chaining feels natural until you want to call a function outside the prototype. Then you either need to modify the prototype and account for collisions or use a different approach, such as function composition.
• Enjoy code they can read and understand

  Common FP is intended to be read as well as used. Most JavaScript devs should be able to browse the utilities to understand how they work. My goal is to provide a positive debugging experience.

Who Isn't This For?#

Common FP is not for everyone. You may prefer other libraries if you

• Are content with your current utilities.

  Common FP may feel odd and unnecessary to you. That's fine! Keep writing code in a way that's comfortable for you and your team.
• Are already familiar with functional programming.

  If Ramda or Sanctuary makes sense to you, then Common FP may feel watered down and missing what you like about functional programming.
• Prefer less opinionated code.

  Common FP is opinionated and will throw errors when you use it in an unintended way. For example, mapValues requires you to pass a function, whereas Lodash provides a default. Calling mapValues without a function doesn't make sense to me; thus, I enforce that convention. This is one opinion of many that won't be shared by everyone - which is okay :)