sequences

API

sequences : object

Kind: global namespace

• sequences : object
  • .Sequence
    • new Sequence()
    • sequence.read(recycle)
    • sequence.pipe(sequenceConstructor, ...args)
  • .Assert ⇒ Sequence
  • .Count ⇒ Sequence
  • .Drain ⇒ Sequence
  • .Each ⇒ Sequence
  • .Filter ⇒ Sequence
  • .FromArray ⇒ Sequence
  • .FromBlocks ⇒ Sequence
  • .FromIterator ⇒ Sequence
  • .From ⇒ Sequence
  • .FromObject ⇒ Sequence
  • .FromSet ⇒ Sequence
  • .Map ⇒ Sequence
  • .Reduce ⇒ Sequence
  • .Slice ⇒ Sequence
  • .Splice ⇒ Sequence
  • .ToArray ⇒ Sequence
  • .ToBlocks ⇒ Sequence
  • .ToObject ⇒ Sequence
  • .ToSet ⇒ Sequence

sequences.Sequence

Kind: static class of sequences

• .Sequence
  • new Sequence()
  • sequence.read(recycle)
  • sequence.pipe(sequenceConstructor, ...args)

new Sequence()

Sequence is the base sequence class. it should always be subclassed. sequence constructors should never require new.

sequence.read(recycle)

read is the core method of a sequence. read should return the next value in the sequence. if there are no more values to read, read should return Sequence.END

Kind: instance method of Sequence
Params

• recycle - a 'container' value to re-use when returning the next value. always optional.

sequence.pipe(sequenceConstructor, ...args)

// this
let seq = From(1, 2, 3, 4);
seq = Slice(seq, 0, 10);
seq = Assert(seq, (val, i) => Number.isInteger(val));
seq = ToArray(seq);

// is equivalent to this
const seq = From(1, 2, 3, "4")
   .pipe(Slice, 0, 10)
   .pipe(Assert, (val, i) => Number.isInteger(val))
   .pipe(ToArray);

pipe is a utility method to wrap one sequence in another.

Kind: instance method of Sequence
Params

• sequenceConstructor - the constructor function for another sequence. pipe assumes the constructor takes a source sequence as its first argument
• ...args * - any number of additional args to pass into sequenceConstructor

sequences.Assert ⇒ Sequence

let Assert = require('@somesocks/sequences/Assert');
let From = require('@somesocks/sequences/From');
let ToArray = require('@somesocks/sequences/ToArray');

let isInteger = (val) => Number.isInteger(val);

// val is [ 1, 2, 3, 4 ]
let val = From(1, 2, 3, 4)
  .pipe(Assert, isInteger)
  .pipe(ToArray)
  .read();

// throws an assertion error
let val2 = From(1, 2, 3, "4")
  .pipe(Assert, isInteger)
  .pipe(ToArray)
  .read();

Assert is a sequence varructor that builds a sequence to run an assertion against every value in the sequence

Kind: static property of sequences
Params

• source Sequence - a source sequence
• assert function - an assertion function
• error function - an error builder function

sequences.Count ⇒ Sequence

let Count = require('@somesocks/sequences/Count');
let Slice = require('@somesocks/sequences/Slice');
let ToArray = require('@somesocks/sequences/ToArray');

// val is [ 0, 1, 2, 3 ]
let val = Count()
  .pipe(Slice, 0, 4)
  .pipe(ToArray)
  .read();

Count is a sequence constructor that builds a sequence that counts integers upward Count never terminates, so make sure to add a terminating sequence like a Slice somewhere after it.

Kind: static property of sequences
Params

• start number - the number to start counting from

sequences.Drain ⇒ Sequence

 // returns Sequence.END
 Count()
   .pipe(Slice, 0, 4)
   .pipe(Drain)
   .read();

Drain is a sequence constructor wraps a source sequence, and when read is called it reads the entire sequence and throws it away. Useful for sequences with side-effects.

Kind: static property of sequences
Params

• source Sequence - the source sequence to drain

sequences.Each ⇒ Sequence

 // should log:
 // element 0 is 1
 // element 1 is 2
 // element 2 is 3
 Count()
   .pipe(Slice, 1, 4)
   .pipe(Each, (val, i) => console.log(`element ${i} is ${val}`))
   .pipe(Drain)
   .read();

Each is a sequence constructor wraps a source sequence, and when read is called it reads the entire sequence and throws it away. Useful for sequences with side-effects.

Kind: static property of sequences
Params

• source Sequence - the source sequence to drain
• each function - a function to get called for each value

sequences.Filter ⇒ Sequence

 // res is [0, 10, 20, 30, 40]:
 let res = Count()
   .pipe(Slice, 0, 50)
   .pipe(Filter, (val, i) => (val % 10 === 0))
   .pipe(ToArray)
   .read();

Filter removes some items from a sequence.

Kind: static property of sequences
Params

• source Sequence - a source sequence
• filter function - a filter function

sequences.FromArray ⇒ Sequence

 // res is [1, 2, 3]:
 let res = FromArray([ 1, 2, 3 ])
   .pipe(ToArray)
   .read();

FromArray builds a sequence from an array.

Kind: static property of sequences
Params

• values array - values to return in the sequence, in order

sequences.FromBlocks ⇒ Sequence

 // res is [1, 2, 3, 4, 5, 6]:
 let res = From([ 1, 2, 3 ], [4, 5, 6])
   .pipe(FromBlocks)
   .pipe(ToArray)
   .read();

FromBlocks 'flattens' a sequence of arrays into a sequence of elements.

Kind: static property of sequences
Params

• source Sequence - a sequence of arrays

sequences.FromIterator ⇒ Sequence

FromIterator builds a sequence from an iterator

Kind: static property of sequences
Params

• iterator Iterator - iterator to convert into a sequence

sequences.From ⇒ Sequence

 // res is [1, 2, 3]:
 let res = From(1, 2, 3)
   .pipe(ToArray)
   .read();

From builds a sequence from its arguments.

Kind: static property of sequences
Params

• ...values * - values to return in the sequence, in order

sequences.FromObject ⇒ Sequence

 // res is [{ key: 'a', value: 1 }, { key: 'b', value: 2 }]:
 let res = FromObject({ a: 1, b: 2 })
   .pipe(ToArray)
   .read();

FromObject builds a sequence of key-value pairs from an object.

Kind: static property of sequences
Params

• obj object - object from which to return a sequence of key-value pairs

sequences.FromSet ⇒ Sequence

FromSet builds a sequence from a Set

Kind: static property of sequences
Params

• set Set - set to convert into a sequence

sequences.Map ⇒ Sequence

 // res is [1, 2, 3]:
 let res = Count()
   .pipe(Slice, 0, 4)
   .pipe(Map, (val, i) => val + 1)
   .pipe(ToArray)
   .read();

Map transforms each element in a sequence.

Kind: static property of sequences
Params

• source Sequence - a source sequence
• map function - a map function

sequences.Reduce ⇒ Sequence

 // res is 6:
 let res = Count()
   .pipe(Slice, 0, 4)
   .pipe(Reduce, (state, val, i) => state + val)
   .read();

Reduce 'reduces' a sequence of elements to a single result.

Kind: static property of sequences
Params

• source Sequence - a source sequence
• reduce function - a reduce function
• state * - the initial value of the state

sequences.Slice ⇒ Sequence

 // res is [1, 2, 3]:
 let res = Count()
   .pipe(Slice, 0, 4)
   .pipe(ToArray)
   .read();

Slice 'slices' out a piece of a sequence to use

Kind: static property of sequences
Params

• source Sequence - a source sequence
• start integer - the index to start from (inclusive)
• end integer - the index to end at (exclusive)

sequences.Splice ⇒ Sequence

 // res is [1, 2, 3, 4, 5, 6]:
 let res = Splice(From(1, 2, 3), From(4, 5, 6))
   .pipe(ToArray)
   .read();

Splice 'splices' several sequences together, concatenating them into a single sequence

Kind: static property of sequences
Params

• ...sources Sequence - the source sequences

sequences.ToArray ⇒ Sequence

 // res is [1, 2, 3]:
 let res = From(1, 2, 3)
   .pipe(ToArray)
   .read();

ToArray converts a sequence into an array.

NOTE: ToArray will always return exactly once. If the source sequence is empty, ToArray will return an empty array.

Kind: static property of sequences
Params

• source Sequence - the source sequence

sequences.ToBlocks ⇒ Sequence

 // res is [ [1, 2, 3], [4, 5, 6] ]:
 let res = From(1, 2, 3, 4, 5, 6)
   .pipe(ToBlocks, 3)
   .pipe(ToArray)
   .read();

ToBlocks converts a sequence into a sequence of 'blocks' (fixed-size arrays of the elements)

Kind: static property of sequences
Params

• source Sequence - the source sequence
• size number - the size of blocks to emit

sequences.ToObject ⇒ Sequence

 // res is { a: 1, b: 2 }:
 let res = From({ key: 'a', value: 1 }, { key: 'b', value: 2 })
   .pipe(ToObject)
   .read();

ToObject converts a sequence into an object The sequence must be a sequence of key-value pairs, structured as an object with a 'key' and a 'value' property.

NOTE: ToObject will always return exactly once. If the source sequence is empty, ToObject will return an empty object.

Kind: static property of sequences
Params

• source Sequence - the source sequence

sequences.ToSet ⇒ Sequence

ToSet converts a sequence into a Set

NOTE: ToSet will always return exactly once. If the source sequence is empty, ToSet will return an empty Set.

Kind: static property of sequences
Params

• source Sequence - the source sequence