node package manager

lazy-seq

lazy-seq

Lazy sequences

Build Status NPM version Dependency Status devDependency Status Code Climate

Lazy?

The list structure could be defined as

data Seq a = Nil | Cons a (Seq a)

The Cons constuctor takes two arguments, so there are four different laziness variants:

Cons (Strict a) (Strict (Seq a)) -- 1. fully strict
Cons (Lazy a)   (Strict (Seq a)) -- 2. lazy values
Cons (Strict a) (Lazy (Seq a))   -- 3. lazy structure
Cons (Lazy   a) (Lazy (Seq a))   -- 4. fully lazy

This module implements the third variant: lazy structure, but strict values.

Example

var ones = lazyseq.cons(1, function () { return ones; });
console.log(ones === ones.tail()); // true! 

Why?

This package is originally made to optimise shrink operations in jsverify, a property-based testing library.

API

  • nil : Seq a — Empty sequence.

  • cons : (head : a, tail : Array a | Seq a | () → Array a | () → Seq a) → Seq a : Cons a value to the front of a sequence (list or thunk).

  • .isNil : Boolean — Constant time check, whether the sequence is empty.

  • .toString : () → String — String representation. Doesn't force the tail.

  • .length : () → Nat — Return the length of the sequene. Forces the structure.

  • .toArray : () → Array a — Convert the sequence to JavaScript array.

  • .fold : (z : b, f : (a, () → b) → b) → b — Fold from right.

    fold nil x f        = x
    fold (cons h t) x f = f x (fold t x f)
  • .head : () → a — Extract the first element of a sequence, which must be non-empty.

  • .tail : () → Seq a — Return the tail of the sequence.

    tail nil        = nil
    tail (cons h t) = t
  • .nth : (n : Nat) → a — Return nth value of the sequence.

  • .take : (n : Nat) → Seq a — Take n first elements of the sequence.

  • .drop : (n : Nat) → Seq a — Drop n first elements of the sequence.

  • .map : (f : a → b) : Seq b — The sequence obtained by applying f to each element of the original sequence.

  • .append : (ys : Seq a | Array a) : Seq a — Append ys sequence.

  • .filter : (p : a -> bool) : Seq a — filter using p predicate.

  • *.every : (p = identity: a -> b) : b | true — return first falsy value in the sequence, true otherwise. N.B. behaves slightly differently from Array::every.

  • *.some : (p = identity: a -> b) : b | false — return first truthy value in the sequence, false otherwise. N.B. behaves slightly differently from Array::some.

  • *.contains : (x : a) : bool — Returns true if x is in the sequence.

  • *.containsNot : (x : a) : bool — Returns true if x is not in the sequence.

  • fromArray: (arr : Array a) → Seq a — Convert a JavaScript array into lazy sequence.

  • singleton: (x : a) → Seq a — Create a singleton sequence.

  • append : (xs... : Array a | Seq a | () → Array a | () → Seq a) → Seq a : Append one sequence-like to another.

  • iterate : (x : a, f : a → a) → Seq a — Create an infinite sequence of repeated applications of f to x: x, f(x), f(f(x))….

  • fold : (seq : Seq a | Array a, z : b, f : (a, () → b) → b) : b — polymorphic version of fold. Works with arrays too.

Release History

  • 1.0.02015-07-28 — Stable
    • Consider stable
    • singleton constructure
    • .contains, .containsNot, .every and .some methods
  • 0.2.02015-04-21filter
  • 0.1.02015-03-21append
  • 0.0.22014-12-20 — Fixed fold
  • 0.0.12014-12-20 — Initial release

Contributing

  • README.md is generated from the source with ljs
  • Before creating a pull request run make test, yet travis will do it for you.