arizonatribe / vanillas

Dependency-free, low-level, vanilla JavaScript utility functions. Inspired by Lodash & Ramda but faster.

Vanillas

JavaScript utility functions. Comparable to Lodash or Ramda, but faster. In some cases it even outperforms native implementations (or leverages native implementations that are messy to type out).

Why Another Utils Lib?

Lodash/Underscore created an API many years ago which is unfavorable to Currying. For currying to be possible you need the final argument to your function to be the data on which you operate (rather than the first arg). And although Lodash/Underscore has an "fp" (functional programming) subset, the fundamental flaw in the argument order can't be corrected.

A similar utils library Ramda was created as a classic functional programming library, and the most notable change was to reorder the arguments to be favorable to currying. Ramda took it a step further than than (perhaps too far) of making every function in the whole library curried. This isn't always desired. But the more critical flaw with Ramda is it is slow. Very slow.

Vanillas was created to correct those perceived flaws in both Lodash/Underscore and Ramda. It outperforms those libraries, makes currying possible, yet allows you to opt-in to currying.

Docs

View the full docs. These are generated from - and always in-sync with - the JsDoc code annotations.

Curried vs Non-Curried

Importing from the root vanillas namespace yields all the non-curried utility functions (including the curry() function itself if you want to do your own). To use the curried versions of the Vanillas utility functions though, just import from the vanillas/curried directory rather than from the root.

Installation

npm install vanillas

Benchmarks

Run any of the files in the benchmark/test/ directory.

Examples (run one or more benchmark tests, space-delimited):

npm run benchmark compose
npm run benchmark propAt
npm run benchmark mapObject
npm run benchmark compose mapObject propAt

Or you can run all of them (grab a cup of coffee while you wait):

npm run benchmark

View Current Benchmarks

vanillas's Issues

Vague types with the new type definitions

Came across a scenario today where I am needing to use clone() in TS. The issue I'm seeing is that the generated type definition says that this accepts an object | object[] and returns the same. However, this doesn't allow for the implementer to define what kind of object this is, so therefore typescript complains about something not existing on the returned object.

Example:
https://codesandbox.io/embed/vanillas-clone-example-52nzh?fontsize=14&hidenavigation=1&theme=dark

import clone from "vanillas/clone";

const sampleObject: {
  hello: string
} = {
  hello: "world"
}

const something = clone(sampleObject)

console.log(something.hello)

In this example, .hello does not exist on the type. I think the solution here would be to allow for a generic type. An interface like

export default function clone<T>(obj: T | T[]): T | T[]

would probably do the trick, however I'm not sure how JSDoc would be able to generate this.

`isEqual` with empty array as first argument

Hi, when I was using isEqual, I was receiving an unexpected true value when trying to compare an empty array to another array.

import isEqual from "vanillas/isEqual";
isEqual([], [1])

From looking at the source, it seems to be due to the .every usage and .every evaluating to true for an empty array.