Fpx

Overview

fpx: Functional Programming eXtensions for JavaScript. Lightweight replacement for Lodash. Stuff that should be built into the language.

Features:

• Higher-order functions for data structures.
  • Common FP tools like map, filter, and many more.
  • Compatible with arbitrary iterables such as lists, sets, maps, dicts.
• Boolean tests for common types and interfaces.
• Minifiable type assertions.
• Type conversions.
• Tuned for performance.
• Small and dependency-free. Single file. Native JS module.

Differences from Lodash:

• Supports arbitrary iterables and iterators, including sets and maps.
• Type assertions and conversions.
• Much smaller and simpler.

TOC

• #Usage
• #Why
• #Perf
• #API
  • #function bind
  • #function not
  • #function is
  • #function truthy
  • #function falsy
  • #function isNil
  • #function isSome
  • #function isBool
  • #function isNum
  • #function isFin
  • #function isFinNeg
  • #function isFinPos
  • #function isInt
  • #function isNat
  • #function isIntNeg
  • #function isIntPos
  • #function isNaN
  • #function isInf
  • #function isBigInt
  • #function isStr
  • #function isSym
  • #function isKey
  • #function isJunk
  • #function isComp
  • #function isPrim
  • #function isFun
  • #function isFunSync
  • #function isFunGen
  • #function isFunAsync
  • #function isFunAsyncGen
  • #function isObj
  • #function isStruct
  • #function isArr
  • #function isReg
  • #function isDate
  • #function isValidDate
  • #function isInvalidDate
  • #function isSet
  • #function isMap
  • #function isPromise
  • #function isIter
  • #function isIterAsync
  • #function isIterator
  • #function isIteratorAsync
  • #function isGen
  • #function isCls
  • #function isDict
  • #function isList
  • #function isSeq
  • #function isVac
  • #function isScalar
  • #function isInst
  • #function isListOf
  • #function isEmpty
  • #function hasMeth
  • #function req
  • #function opt
  • #function reqInst
  • #function optInst
  • #function only
  • #function arrOf
  • #function prim
  • #function bool
  • #function num
  • #function fin
  • #function int
  • #function nat
  • #function intPos
  • #function str
  • #function dict
  • #function struct
  • #function scalar
  • #function inst
  • #function add
  • #function sub
  • #function mul
  • #function div
  • #function rem
  • #function lt
  • #function gt
  • #function lte
  • #function gte
  • #function neg
  • #function inc
  • #function dec
  • #function nop
  • #function True
  • #function False
  • #function id
  • #function di
  • #function val
  • #function panic
  • #function render
  • #function show
  • #function npo
  • #function hasOwn
  • #function hasOwnEnum
  • #function mut
  • #function mapDict
  • #function pick
  • #function omit
  • #function pickKeys
  • #function omitKeys
  • #function more
  • #function alloc
  • #function arr
  • #function arrCopy
  • #function slice
  • #function keys
  • #function values
  • #function valuesCopy
  • #function entries
  • #function reify
  • #function vac
  • #function indexOf
  • #function includes
  • #function concat
  • #function append
  • #function prepend
  • #function len
  • #function hasLen
  • #function each
  • #function map
  • #function mapMut
  • #function mapCompact
  • #function filter
  • #function reject
  • #function compact
  • #function remove
  • #function fold
  • #function find
  • #function procure
  • #function every
  • #function some
  • #function head
  • #function last
  • #function init
  • #function tail
  • #function take
  • #function count
  • #function compare
  • #function compareFin
  • #function sort
  • #function reverse
  • #function index
  • #function group
  • #function partition
  • #function sum
  • #function zip
  • #function mapFrom
  • #function range
  • #function span
  • #function times
  • #function repeat
  • #function set
  • #function setCopy
• #License
• #Misc

Usage

In browsers and Deno, import by URL:

import * as f from 'https://cdn.jsdelivr.net/npm/fpx@0.12.3/fpx.mjs'

When using Node or NPM-oriented bundlers like Esbuild:

npm i -E fpx

import * as f from 'fpx'
import * as f from './node_modules/fpx/fpx.mjs'

Why

• Built-ins are insufficient.
• Other libraries are too large.
• Other libraries are annoying to use.
• Other libraries lack vital tools.

Simplicity

Programs must be written for people to read, and only incidentally for machines to execute.

— Abelson & Sussman, "Structure and Interpretation of Computer Programs"

I believe that all code should strive to be simple and educational. This gives me a massive distaste for most code.

Fpx is tuned for brevity, readability, clarity in addition to performance. If you want to understand how this kind of library works, how higher-order functions work, how to manipulate JS data structures, Fpx should hopefully provide a good read.

Assertions

Assertions go a long way in debugging. Fail fast, catch bugs early. In asynchronous code, validating inputs as early as possible, instead of letting it fail mysteriously later, can save you hours of debugging.

Here's the traditional way of doing assertions:

function someHigherOrderFunction(fun) {
  if (typeof fun !== 'function') {
    throw TypeError(`expected a function, got ${fun}`)
  }
  // Actual code after the assertion.
}

someHigherOrderFunction({one: 10})
// uncaught TypeError: expected a function, got [object Object]

Annoying to type and really bad for minification. Some folks strip assertions from production builds, but I find the idea flawed. Even in production, failing fast is better than failing mysteriously, and assertions help with debugging when it inevitably fails.

Fpx provides a better alternative:

function someHigherOrderFunction(fun) {
  f.req(fun, f.isFun)
  // Actual code after the assertion.
}

someHigherOrderFunction({one: 10})
// uncaught TypeError: expected {"one":10} to satisfy test isFun

Much better. Easy to type with editor autocompletion, produces good error messages, and minifies really well. In a minified build, the function name will be mangled, which is good for bundle size. The mangled name is a non-issue with a source map, which you need for debugging anyway.

To support this style of coding, Fpx provides #req and a bevy of boolean tests.