lz

the fastest¹ functional lazy library for JavaScript.

this isn't an FP do-it-all library² -- this is a collection of useful functions for working with lists and text as efficiently as possible.

Examples

Fizzbuzz

var three = lz.cycle(['', '', 'fizz'])
var five = lz.cycle(['', '', '', '', 'buzz'])
var fizzbuzz = lz.zipWith(function (a, b) { return a + b }, three, five)

fizzbuzz.take(5).toArray()

Factorial

  // Return factorial of 4
  // note you should use `new` but you don't have to
  new lz([1, 2, 3, 4]).scanl(function (a, b) { return a * b }).at(3)

ProjectEuler Problem 1

  lz.range(1, 999)
  .filter(function (n) { return n % 3 === 0 || n % 5 === 0 })
  .foldl(function (a, b) { return a + b })

API

• chainable

  • compact
  • concat
  • cycle
  • drop
  • dropWhile
  • filter
  • flatten
  • init
  • map
  • scanl
  • sort
  • tail
  • take
  • takeWhile
  • zipWith

• value

  • all
  • and
  • any
  • at
  • foldl
  • elem
  • head
  • last
  • nil
  • max
  • min
  • or
  • $ | toArray
  • toString

• static

  • concatMap
  • cycle
  • flatten
  • foldl
  • iterate
  • lines
  • max
  • min
  • range
  • repeat
  • replicate
  • words
  • zipWith

chainable

The following functions return this (Object lz)

compact()

Lazily removes falsy (undefined, null, "", 0, NaN) values from the list.

[true, false, true, false]
  .lz()
  .compact()
  .take(2)
  .toArray()
// = [true, true]

concat(Array || [Object lz])

Lazily concatenate the list passed in to the current list.

['hello']
  .lz()
  .concat(['laziness'])
  .take(2)
  .toArray()
// = ['hello', 'laziness']

[1]
  .lz()
  .concat(lz.cycle([2]))
  .take(4)
  .toArray()
/// = [1, 2, 2, 2]

cycle()

Generates an infinite loop composed of the elements of the current list.

['Na']
  .lz()
  .cycle()
  .take(10)
  .toString(' ') + ' Batman!'
// = Na Na Na Na Na Na Na Na Na Na Batman!

drop(Number)

Removes the amount provided, starting from the current position, from the collection.

[null, null, 1, 2, 3].lz().drop(2).toArray()
// = [1, 2, 3]

dropWhile(Function)

Drops elements from the collection until the function provided returns false.

[1, 2, 3, 4, 5]
  .lz()
  .dropWhile(function (n) { return n < 4 })
  .toArray()
// = [4, 5]

filter(Function)

Lazily removes elements from the collection if the return value from the function provided is not true.

[{ color: 'red' }, { color: 'blue' }, { color: 'pink' }, { color: 'red' }]
  .lz()
  .filter(function (x) { return x.color === 'red' })
  .toArray()
// = [{ color: 'red' }, { color: 'red' }]

flatten(Boolean)

Flattens a nested Array. If shallow is truthy Array is flattened to a single level.

[[1], [2], [3]].lz().flatten().toArray()
// = [1, 2, 3]

init()

Returns all the elements from the collection except for the last one.

[1, 2, 3, 4, 5].lz().init().toArray()
// = [1, 2, 3, 4]

map(Function)

Lazily applies the function provided to each element and replaces the element with the value returned from the function.

['m', 'a', 'p']
  .lz()
  .map(function (a) { return a.toUpperCase() })
  .toArray()
  .join('')
// = 'MAP'

scanl(Function)

Similar to a map and a fold. Lazily returns a list of successive reduced values from the left.

[1, 2, 3]
  .lz()
  .scanl(function (a, b) { return a + b })
  .toArray()
// = [1, 3, 6]

sort(Function)

Array prototype method.

tail()

Extract the elements after the head of a list.

[1, 2, 3, 4, 5].lz().last().toArray()
// = [2, 3, 4, 5]

take(Number)

Replaces the collection with the amount taken from the current collection.

lz('my name is lz').take(2).toString()
// = 'my'

takeWhile(Function)

Replaces the collection with the values taken from the current collection which when applied to the callback function return true.

[1, 2, 3, 4, 5]
  .lz()
  .takeWhile(function (n) { return n < 4 })
  .toArray()
// = [1, 2, 3]

zipWith(Function, Array)

Takes the current list and the list passed in and applies the function to each element in both lists generating a new list from the result.

[1, 2]
  .lz()
  .zipWith(function (a, b) { return a + b }, [2, 1])
  .toArray()
// = [3, 3]

value

These functions return a value.

all(Function)

Applies the function to each element in the collection, returns false if the return value from the function for any of the elements is false, otherwise returns true.

[2, 4, 6, 8, 10]
  .lz()
  .all(function (n) { return n % 2 === 0 })
// = true

and()

Returns false if any element in the list is falsy, otherwise returns true.

[null].lz().and()
// = false

lz('i am true to you').and()
// = true

any(Function)

Applies the function to each element in the collection, returns true if the return value from the function for any of the elements is true, otherwise returns false.

[10, 9, 8, 7, 6]
  .lz()
  .any(function (n) { return n === 9 })
// = true

at(Number)

Returns the element at the index provided. It's zero-based.

lz('chocolate').at(3)
// = 'c'

lz([1, 2, 3]).at(0)
// = 1

foldl(Function)

Reduces the list down to a single value from left to right.

[1, 2, 3, 4, 5]
  .lz()
  .foldl(function (a, b) { return a + b })
// = 15

elem(Generic)

Returns true if the list contains the item provided.

[1, 2, 3, 4, 5]
  .lz()
  .elem(6)
// = false

[null, 0, false, NaN, undefined]
  .lz()
  .elem(NaN)
// = true

head()

Extracts the first element of the collection.

lz('first').head()
// = 'f'

last()

Extracts the last element in the collection.

lz('last').last()
// = 't'

nil()

Returns true if the list is empty or filled with empty values. Otherwise returns false.

[].lz().nil()
// = true

[null, null].lz().nil()
// = true

[false].lz().nil()
// = false

max(Function)

Returns the largest element in the collection. If a function is provided the callback function will be applied to each element before comparing.

[1, 2, 3].lz().max()
// = 3

min(Function)

Returns the smallest element in the collection. If a function is provided the callback function will be applied to each element before comparing.

[1, 2, 3].lz().min()
// = 1

or()

Returns true if any element in the list is truthy, otherwise returns false.

[true, false, true].lz().or()
// = true

toArray()

Forceful method which returns an Array. Alias is $().

[1, 2, 3].lz().take(2).toArray()
// = [1, 2]

toString()

Forceful method which returns the result as a String.

lz('Bananas').toString()
// = Bananas

static

These functions are part of the lz Object namespace.

concatMap(Function, Array)

Returns a list by applying the function provided to all elements in the list and then concatenating the returned list into the result.

lz.concatMap(function (a) { return [a, a] }, [1, 2, 3])
// = [1, 1, 2, 2, 3, 3]

cycle(Array)

See lz.prototype.cycle.

flatten(Array, Boolean)

See lz.prototype.flatten.

foldl(Function, Array)

See lz.prototype.foldl.

iterate(Function, Number)

Creates an infinite list by applying the function repeatedly to the last element in the list, starting with the number provided.

lz.iterate(function (x) { return x + 1 }, 1).take(5).toArray()
// = [1, 2, 3, 4, 5]

lines(String)

Convert a string into a list split by lines.

lz.lines('1. One\n2. Two').toArray()
// = ['1. One', '2. Two']

max(Array, Function)

See lz.prototype.max.

min(Array, Function)

See lz.prototype.min.

range(Number, Number)

Create a finite or infinite list from a range of numbers.

lz.range(1, Infinity).take(5).toArray()
// = [1, 2, 3, 4, 5]

lz.range(5, 10).toArray()
// = [5, 6, 7, 8, 9, 10]

lz.range(1, 10).filter(function (x) { return x % 3 === 0 }).toArray()
// = [3, 6, 9]

repeat(Number)

Creates an infinite list with just a single Number as the value. Same as lz.cycle([Number])

lz.repeat(4).take(7).toArray()
// = [4, 4, 4, 4, 4, 4, 4]

lz.repeat('ya').take(3).toString(' ')
// = 'ya ya ya'

replicate(Number, Number)

Creates a finite list with just a single Number as the value. Similar to lz.repeat(Number).take(Number)

lz.replicate(3, 1).toArray()
// = [1, 1, 1]

lz.replicate(1, 3).toArray()
// = [3]

words(String)

Convert a string into a list split by words.

lz.lines('My cat is also lazy').toArray()
// = ['My', 'cat', 'is', 'also', 'lazy']

zipWith(Function, Array, Array)

See lz.prototype.zipWith.

Speed

It's fast-as-fuck™.

I have included benchmarks in the repo so you can run them for yourself.

If you're working with small lists and/or iterating through all elements in a collection then I recommend lo-dash.

If you plan on being lazy or working with infinite lists then this is the right tool for that job.

Your mileage may vary.

License

MIT