Iterator-cascade-callbacks NPM

Iterator Cascade Callbacks

Iterator that chains callback function execution

Requirements

NodeJS dependencies may be installed via NPM...

npm install

Notice as of version 0.0.6 NodeJS dependencies are for development only, ie. if utilizing this project within other applications or as a submodule, then no dependencies are required.

Quick Start

NodeJS projects may use npm to install iterator-cascade-callbacks as a dependency...

npm install iterator-cascade-callbacks

... or as a development dependency via --save-dev command-line flag...

npm install --save-dev iterator-cascade-callbacks

... Check NodeJS Examples for details on how to import this project within your own source code.

Web projects, such has those hosted on GitHub Pages, are encouraged to utilize Git Submodules instead...

Bash Variables

_module_name='iterator-cascade-callbacks'
_module_https_url="https://github.com/javascript-utilities/iterator-cascade-callbacks.git"
_module_base_dir='assets/javascript/modules'
_module_path="${_module_base_dir}/${_module_name}"

Bash Submodule Commands

cd "<your-git-project-path>"


git checkout gh-pages

mkdir -vp "${_module_base_dir}"


git submodule add -b main\
                  --name "${_module_name}"\
                  "${_module_https_url}"\
                  "${_module_path}"

Your ReadMe File

Suggested additions for your ReadMe.md file so everyone has a good time with submodules

Clone with the following to avoid incomplete downloads


    git clone --recurse-submodules <url-for-your-project>


Update/upgrade submodules via


    git submodule update --init --merge --recursive

Commit and Push

git add .gitmodules
git add "${_module_path}"


## Add any changed files too


git commit -F- <<'EOF'
:heavy_plus_sign: Adds `javascript-utilities/iterator-cascade-callbacks#1` submodule



**Additions**


- `.gitmodules`, tracks submodules AKA Git within Git _fanciness_

- `README.md`, updates installation and updating guidance

- `_modules_/iterator-cascade-callbacks`, Iterator that chains callback function execution
EOF


git push origin gh-pages

:tada: Excellent :tada: your project is now ready to begin unitizing code from this repository!

Usage

Examples on how to utilize this repository

NodeJS Examples

#!/usr/bin/env node


'use strict';


const {
  Callback_Object,
  Iterator_Cascade_Callbacks,
  Stop_Iteration,
  Pause_Iteration,
} = require('iterator-cascade-callbacks');


/**
 * Generator that produces Fibonacci sequence
 * @see {link} https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators
 */
function* fibonacci() {
  let current = 0;
  let next = 1;
  while (true) {
    let reset = yield current;
    [current, next] = [next, next + current];
    if (reset) {
      current = 0;
      next = 1;
    }
  }
}


const icc = new Iterator_Cascade_Callbacks(fibonacci);

icc.filter((value) => {
  return value % 2 === 0;
}).skip(1).map((evens) => {
  return evens / 2;
}).take(5);


const collection = icc.collect([]);

console.log(collection);
//> [ 1, 4, 17, 72, 305 ]

The above filters even numbers from fibonacci Generator, skips the first even result, divides results by two, limits iteration to five results, and finally collects values to an array.

To achieve the same output but without Iterator_Cascade_Callbacks class, code may be similar to...

'use strict';


let match_count = 0;
let skip_count = 0;
let collection = [];

for (let value of fibonacci()) {
  if (!(value % 2 === 0)) {
    continue;
  }

  skip_count++;
  if (skip_count <= 1) {
    continue;
  }

  collection.push(value / 2);
  match_count++;
  if (match_count >= 5) {
    break;
  }
}

console.log(collection);

Web Application Example

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Iterator Cascade Callbacks Example</title>
    <script src="/assets/javascript/modules/iterator-cascade-callbacks/iterator-cascade-callbacks.js" defer></script>
    <script src="/assets/javascript/index.js" defer></script>
  </head>
  <body>
    <code>
      const counter = new Counter(<span id="code__span__counter__start">0</span>);
      <br>
      const icc = new Iterator_Cascade_Callbacks(counter);
      <br>
      <br>

      const collection = icc.filter((value) =&gt; {
      <div style="text-indent: 2em;">
        return value % <span id="code__span__filter_modulo">2</span> === 0;
      </div>
      }).map((value) =&gt; {
      <div style="text-indent: 2em;">
        return value * <span id="code__span__map_multiplier">1</span>;
      </div>
      }).take(<span id="code__span__take_amount">2</span>).collect([]);
    </code>
    <br>
    <br>

    <div id="output-text__container">
      <label for="output-text__results">Results: </label>
      <input id="output-text__results" type="text" value="" readonly>
    </div>
    <br>

    <div id="input-text__container">
      <label for="input-text__counter__start">Counter Start: </label>
      <input id="input-text__counter__start" type="text" value="0">
      <br>

      <label for="input-text__filter_modulo">Filter Modulo: </label>
      <input id="input-text__filter_modulo" type="text" value="2">
      <br>

      <label for="input-text__map_multiplier">Map Multiplier: </label>
      <input id="input-text__map_multiplier" type="text" value="1">
      <br>

      <label for="input-text__take_amount">Take Amount: </label>
      <input id="input-text__take_amount" type="text" value="2">
    </div>

    <div id="button__container">
      <input id="button__iterate" type="button" value="Iterate">
    </div>
  </body>
</html>

assets/javascript/index.js

'use strict';


class Counter {
  constructor(value = -1) {
    this.value = value;
    this.done = false;
  }

  next() {
    this.value++;
    return this;
  }

  [Symbol.iterator]() {
    return this;
  }
};


window.addEventListener('load', () => {
  const output_text__results = document.getElementById('output-text__results');

  const input_text__counter__start = document.getElementById('input-text__counter__start');
  const code__span__counter__start = document.getElementById('code__span__counter__start');

  const input_text__filter_modulo = document.getElementById('input-text__filter_modulo');
  const code__span__filter_modulo = document.getElementById('code__span__filter_modulo');

  const input_text__map_multiplier = document.getElementById('input-text__map_multiplier');
  const code__span__map_multiplier = document.getElementById('code__span__map_multiplier');

  const input_text__take_amount = document.getElementById('input-text__take_amount');
  const code__span__take_amount = document.getElementById('code__span__take_amount');

  const button__iterate = document.getElementById('button__iterate');
  button__iterate.addEventListener('click', () => {
    console.error('CLICKED!');
    /**
     * Parse inputs
     */
    let count_start = input_text__counter__start.value;
    if (isNaN(count_start)) {
      count_start = 0;
      input_text__counter__start = count_start;
    }
    code__span__counter__start.innerText = count_start;

    let filter_modulo = Number(input_text__filter_modulo.value);
    if (isNaN(filter_modulo)) {
      filter_modulo = 1;
      input_text__filter_modulo.value = filter_modulo;
    }
    code__span__filter_modulo.innerText = filter_modulo;

    let map_multiplier = Number(input_text__map_multiplier.value);
    if (isNaN(map_multiplier)) {
      map_multiplier = 1;
      input_text__map_multiplier.value = map_multiplier;
    }
    code__span__map_multiplier.innerText = map_multiplier;

    let take_amount = Number(input_text__take_amount.value);
    if (isNaN(take_amount)) {
      take_amount = 1;
      input_text__take_amount.value = take_amount;
    }
    code__span__take_amount.innerText = take_amount;

    const counter = new Counter(count_start);
    const icc = new Iterator_Cascade_Callbacks(counter);

    icc.filter((value) => {
      return value % filter_modulo === 0;
    }).map((value) => {
      return value * map_multiplier;
    }).take(take_amount);

    const collection = icc.collect([]);

    console.log('collection ->', collection);
    const results = `[ ${collection.join(', ')} ]`;
    output_text__results.value = results;
  });
});

API

Documentation for classes, methods, paramaters, and custom types/data-structures

Class `Stop_Iteration`

Custom error type to permanently stop iteration prematurely

const icc = new Iterator_Cascade_Callbacks([1, 2, 3, 4]);

const collection = icc.map((value, index_or_key) => {
  if (index_or_key > 2) {
    throw new Stop_Iteration('map says to stop at indexes greater than 2');
  }
  return value;
}).collect([]);

console.log(collection);
//> [ 1, 2, 3 ]

Method `Stop_Iteration.constructor`

Builds new instance of Stop_Iteration for throwing

Parameters

{string} message - Error message to print

Class `Pause_Iteration`

Custom error type to temporarily stop iteration prematurely

Method `Pause_Iteration.constructor`

Parameters

{string} message - Error message to print

Class `Callback_Object`

Classy object for storing wrapper function state between iterations

Method `Callback_Object.constructor`

Builds new instance of Callback_Object to append to Iterator_Cascade_Callbacks.callbacks list

Parameters

{Callback_Wrapper} callback_wrapper - Function wrapper that handles input/output between Callback_Function and Iterator_Cascade_Callbacks

Method `Callback_Object.call`

Calls this.wrapper function with reference to this Callback_Object and Iterator_Cascade_Callbacks

Parameters

{Iterator_Cascade_Callbacks} iterator_cascade_callbacks - Reference to Iterator_Cascade_Callbacks instance

Class `Iterator_Cascade_Callbacks`

Iterator that chains callback function execution

Properties

{Dictionary} state - Data shared between Callback_Wrapper functions on each iteration
{Dictionary} storage - Data shared between Callback_Function for each iteration

Method `Iterator_Cascade_Callbacks.constructor`

Instantiates new instance of Iterator_Cascade_Callbacks from iterable input

Parameters

{any} iterable - Currently may be an array, object, generator, or iterator type

Static Method `*iteratorFromArray`

Converts Array to GeneratorFunction

Parameters

{any[]} array - List any type of values

Yields {Yielded_Tuple} [any, number]

Static Method `*iteratorFromObject`

Converts Object to GeneratorFunction

Parameters

{Dictionary} dictionary - Dictionary of key value pares

Yields {Yielded_Tuple} [any, string]

Static Method `*iteratorFromGenerator`

Converts Iterator class or GeneratorFunction to Generator

Parameters

{GeneratorFunction} iterator - Objects with .next() or [Symbol.iterator]() method defined

Yields {Yielded_Tuple} [any, number]

Static Method `compareValues`

Compares left to right values

Parameters

{any} left - Left-hand side of comparison
{any} right - Right-hand side of comparison

Example

console.log(Iterator_Cascade_Callbacks.compareValues(1, '1'));
//> '=='

console.log(Iterator_Cascade_Callbacks.compareValues(1, 1));
//> '==='

console.log(Iterator_Cascade_Callbacks.compareValues(2, 1));
//> '>'

console.log(Iterator_Cascade_Callbacks.compareValues(2, '3'));
//> '<'

console.log(Iterator_Cascade_Callbacks.compareValues('spam', 'ham'));
//> '!='

console.log(Iterator_Cascade_Callbacks.compareValues({ key: 'value' }, ['foo', 'bar']));
//> '!=='

Static Method `zip`

Returns new instance of Iterator_Cascade_Callbacks that yields lists of either Yielded_Tuple or undefined results

Parameters

{any[]} iterables - List of Generators, Iterators, and/or instances of Iterator_Cascade_Callbacks

Example Equal Length Iterables

const icc_one = new Iterator_Cascade_Callbacks([1,2,3]);
const icc_two = new Iterator_Cascade_Callbacks([4,5,6]);

const icc_zip = Iterator_Cascade_Callbacks.zip(icc_one, icc_two);

for (let [results, count] of icc_zip) {
  console.log('results ->', results, '| count ->', count);
}
//> results -> [ [ 1, 0 ], [ 4, 0 ] ] | count -> 0
//> results -> [ [ 2, 1 ], [ 5, 1 ] ] | count -> 1
//> results -> [ [ 3, 2 ], [ 6, 2 ] ] | count -> 2

Static Method `zipCompareValues`

Zips left and right iterable values and prepends Comparison_Results to values list

Parameters

{any} left - Generator, Iterator, and/or instance of Iterator_Cascade_Callbacks
{any} right - Generator, Iterator, and/or instance of Iterator_Cascade_Callbacks

Example

const left = [ 1, 0, 1, 2, 'foo', {} ]
const right = [ '0', 0, 2, '2', 'bar' ]

const icc = Iterator_Cascade_Callbacks.zipCompareValues(left, right);
const collection = icc.collect([]);

console.log(collection);
//> [
//>   [ '>', 1, '0' ],
//>   [ '===', 0, 0 ],
//>   [ '<', 1, 2 ],
//>   [ '==', 2, '2' ],
//>   [ '!=', 'foo', 'bar' ],
//>   [ '!==', {}, undefined ]
//> ]

Static Method `zipValues`

Returns new instance of Iterator_Cascade_Callbacks that yields either list of values from iterators or undefined results

Parameters

{any[]} iterables - List of Generators, Iterators, and/or instances of Iterator_Cascade_Callbacks

Example Equal Length Iterables

const icc_one = new Iterator_Cascade_Callbacks([1, 2, 3]);
const icc_two = new Iterator_Cascade_Callbacks([4, 5, 6]);

const icc_zip = Iterator_Cascade_Callbacks.zip(icc_one, icc_two);

for (let [results, count] of icc_zip) {
  console.log('results ->', results, '| count ->', count);
}
//> results -> [ 1, 4 ] | count -> 0
//> results -> [ 2, 5 ] | count -> 1
//> results -> [ 3, 6 ] | count -> 2

Example Unequal Length Iterables

const icc_three = new Iterator_Cascade_Callbacks([7, 8, 9]);
const icc_four = new Iterator_Cascade_Callbacks([10, 11]);

const icc_zip = Iterator_Cascade_Callbacks.zip(icc_three, icc_four);

for (let [results, count] of icc_zip) {
  console.log('results ->', results, '| count ->', count);
}
//> results -> [ 9, 10 ] | count -> 2
//> results -> [ 8, 11 ] | count -> 1
//> results -> [ 7, undefined ] | count -> 0

Notes

Parameters that are not an instance of Iterator_Cascade_Callbacks will be converted
Iteration will continue until all iterables result in done value of true

Method `*iterateCallbackObjects`

Converts list of this.callbacks objects to GeneratorFunction

Yields {Callback_Object}

Method `collect`

Collects results from this to either an Array or Object

Parameters

{any[] | Object | any} target - When target is Array values are pushed, when target is Object key value pares are assigned, callback is required for other types
{Collect_To_Function?|number?} callback_or_amount - Callback function for collecting to custom type, or amount to limit known collection object types to
{number?} amount - Limit collection to no more than amount

Returns {any[] | Dictionary | undefined}

Method `collectToArray`

Collects results from this.next() to an Array

Parameters

{any[]} target - Array to push collected values to
{number?} amount - Limit collection to no more than amount

Returns {any[]}

Example

const icc = new Iterator_Cascade_Callbacks([5, 6, 7, 8, 9]);

const collection = icc.filter((value) => {
  return value % 2 === 0;
}).collectToArray([1, 2, 3]);

console.log(collection);
//> [ 1, 2, 3, 6, 8 ]

Method `collectToFunction`

Collects results from this.next() to a callback function target

Parameters

{any} target - Any object or primitive, will be passed to callback function along with value and index_or_key
{Function} callback - Custom callback function for collecting iterated values
{number?} amount - Limit collection to no more than amount

Example

const icc = new Iterator_Cascade_Callbacks({ spam: 'flavored', canned: 'ham' });

const map = new Map();

const collection = icc.collectToFunction(map, (target, value, index_or_key) => {
  target.set(index_or_key, value);
});

console.log(collection);
//> Map(2) { 'spam' => 'flavored', 'canned' => 'ham' }

Method `collectToObject`

Collects results from this.next() to an Object

Parameters

{Object} target - Dictionary like object to assign key value pares to
{number?} amount - Limit collection to no more than amount

Returns dictionary-like object

Example

const icc = new Iterator_Cascade_Callbacks({ spam: 'flavored', canned: 'ham' });

const collection = icc.collectToObject({});

console.log(collection);
//> { spam: 'flavored', canned: 'ham' }

Method `copyCallbacksOnto`

Returns new instance of Iterator_Cascade_Callbacks with copy of callbacks

Parameters

{any} iterable - Any compatible iterable object, iterator, or generator

Example

const iterable_one = [1, 2, 3, 4, 5];
const iterable_two = [9, 8, 7, 6, 5];

const icc_one = new Iterator_Cascade_Callbacks(iterable_one);

icc_one.filter((value) => {
  return value % 2 === 0;
}).map((evens) => {
  return evens / 2;
});

const icc_two = icc_one.copyCallbacksOnto(iterable_two);

console.log('Collection One ->', icc_one.collect([]));
//> [ 1, 2 ]
console.log('Collection Two ->', icc_two.collect([]));
//> [ 4, 3 ]

Method `filter`

Sets this.value if callback function returns truthy, else consumes this.iterator and recomputes value for callback to test

Parameters

{Callback_Function} callback - Function that determines truth of value and/or index_or_key for each iteration
{...any[]} parameters - List of arguments that are passed to callback on each iteration

Returns this {Iterator_Cascade_Callbacks}

Example

const icc = new Iterator_Cascade_Callbacks([9, 8, 7, 6, 5]);

const collection = icc.filter((value) => {
  return value % 2 === 0;
}).collect([]);

console.log(collection);
//> [ 8, 6 ]

Method `forEach`

Executes callback for each iteration

Parameters

{Callback_Function} callback - Function that generally does not mutate value or index_or_key for Iterator_Cascade_Callbacks instance
{...any[]} parameters - List of arguments that are passed to callback on each iteration

Returns this {Iterator_Cascade_Callbacks}

Example

const icc = new Iterator_Cascade_Callbacks([9, 8, 7, 6, 5]);

const collection = icc.forEach((value) => {
  console.log(value);
}).collect([]);

console.log(collection);
//> [ 9, 8, 7, 6, 5 ]

Notes

If mutation of value or index_or_key are desired then map is a better option
No protections are in place to prevent mutation of value or index_or_key Objects

Method `inspect`

Useful for debugging and inspecting iteration state

Parameters

{Callback_Function} callback - Function that logs something about each iteration
{...any[]} parameters - List of arguments that are passed to callback on each iteration

Example

function inspector(value, index_or_key, { callback_object, iterator_cascade_callbacks }, ...parameters) {
  console.log('value ->', value);
  console.log('index_or_key ->', index_or_key);
  console.log('callback_object ->', callback_object);
  console.log('iterator_cascade_callbacks ->', iterator_cascade_callbacks);
}

const icc = new Iterator_Cascade_Callbacks([9, 8, 7, 6, 5]);

const collection = icc.filter((value) => {
  return value % 2 === 0;
}).inspect(inspector).map((even) => {
  return even / 2;
}).inspect(inspector).collect([]);

Method `limit`

Stops iteration when limit is reached

Parameters

{number} amount - Max number of values to compute

Returns this {Iterator_Cascade_Callbacks}

Example

const icc = new Iterator_Cascade_Callbacks([1, 2, 3, 4]);

const collection = icc.limit(2).collect([]);

console.log(collection);
//> [1, 2]

Notes

Useful when iterating over data of indeterminate, or infinite, length
More predictable if ordered at the end of this.callbacks list
Callbacks exist when amount is reached will be called prior to throwing Stop_Iteration

Method `map`

Applies callback to modify value and/or index_or_key for each iteration

Parameters

{Callback_Function} callback - Function may modify value and/or index_or_key
{...any[]} parameters - List of arguments that are passed to callback on each iteration

Returns this {Iterator_Cascade_Callbacks}

Example

const icc = new Iterator_Cascade_Callbacks([9, 8, 7, 6, 5]);

const collection = icc.filter((value) => {
  return value % 2 === 0;
}).map((value) => {
  return value / 2;
}).collect([]);

console.log(collection);
//> [4, 3]

Notes

If callback does not return Yielded_Tuple (array), then results from callback are used as value and initial index_or_key is reused

Method `next`

Updates this.value from chaining this.callbacks list, and this.done from this.iterator.next()

Returns this {Iterator_Cascade_Callbacks}

Example

const icc = new Iterator_Cascade_Callbacks([1, 2, 3, 4]);

for (let [value, index_or_key] of icc) {
  console.log('index_or_key ->', index_or_key, 'value ->', value);
}
//> index_or_key -> 0 value -> 1
//> index_or_key -> 1 value -> 2
//> index_or_key -> 2 value -> 3
//> index_or_key -> 3 value -> 4

Method `skip`

Skip number of iterations

Parameters

{number} amount - Number of iterations to skip past

Returns this {Iterator_Cascade_Callbacks}

Example

const icc = new Iterator_Cascade_Callbacks([0, 1, 2, 3, 4, 5]);

const collection = icc.skip(2).collect([]);

console.log(collection);
//> [ 2, 3, 4, 5 ]

Method `step`

Step over every n iterations

Parameters

{number} amount - Number of iterations to step over

Returns this {Iterator_Cascade_Callbacks}

Example

const icc = new Iterator_Cascade_Callbacks([0, 1, 2, 3, 4, 5]);

const collection = icc.step(1).collect([]);

console.log(collection);
//> [ 1, 3, 5 ]

Method `take`

Pauses/breaks iteration when limit is reached

Parameters

{number} amount - Number of values to compute before pausing

Returns this {Iterator_Cascade_Callbacks}

Throws {Pause_Iteration}

Example

const icc = new Iterator_Cascade_Callbacks([1, 2, 3, 4]);

icc.take(2);

const collection_one = icc.collect([]);
console.log(collection_one);
//> [ 1, 2 ]

const collection_two = icc.collect([]);
console.log(collection_two);
//> [ 3, 4 ]

Notes

If immediately collecting to an object, consider using collect() method instead

Method `valuesAreEqual`

Returns true or false based on if this is equal to other

Parameters

{any|Iterator_Cascade_Callbacks} other - Iterable that is, or can be converted to, instance of Iterator_Cascade_Callbacks

Example

const icc = new Iterator_Cascade_Callbacks([1, 2, 3]);

console.assert(icc.valuesAreEqual([1, 2, 3]) === true);
console.assert(icc.valuesAreEqual([1, 3, 2]) === false);
console.assert(icc.valuesAreEqual('spam') === false);

Method `valuesAreGreaterOrEqual`

Returns true or false based on if this is greater than or equal to other

Parameters

{any|Iterator_Cascade_Callbacks} other - Iterable that is, or can be converted to, instance of Iterator_Cascade_Callbacks

Example

const icc = new Iterator_Cascade_Callbacks([1, 2, 3]);

console.assert(icc.valuesAreGreaterOrEqual([1, 2, 3]) === true);
console.assert(icc.valuesAreGreaterOrEqual([1, 1, 3]) === true);
console.assert(icc.valuesAreGreaterOrEqual([1, 3, 2]) === false);

Method `valuesAreGreaterThan`

Returns true or false based on if this is greater than other

Parameters

{any|Iterator_Cascade_Callbacks} other - Iterable that is, or can be converted to, instance of Iterator_Cascade_Callbacks

Example

const icc = new Iterator_Cascade_Callbacks([1, 2, 3]);

console.assert(icc.valuesAreGreaterThan([1, 2]) === true);
console.assert(icc.valuesAreGreaterThan([1, 2, 3]) === false);

Method `valuesAreLessOrEqual`

Returns true or false based on if this is less than or equal to other

Parameters

{any|Iterator_Cascade_Callbacks} other - Iterable that is, or can be converted to, instance of Iterator_Cascade_Callbacks

Example

const icc = new Iterator_Cascade_Callbacks([1, 2, 3]);

console.assert(icc.valuesAreLessOrEqual([1, 2, 3]) === true);
console.assert(icc.valuesAreLessOrEqual([1, 2, 4]) === true);
console.assert(icc.valuesAreLessOrEqual([1, 1, 2]) === false);

Method `valuesAreLessThan`

Returns true or false based on if this is less than other

Parameters

{any|Iterator_Cascade_Callbacks} other - Iterable that is, or can be converted to, instance of Iterator_Cascade_Callbacks

Example

const icc = new Iterator_Cascade_Callbacks([1, 2, 3]);

console.assert(icc.valuesAreLessThan([1, 3]) === true);
console.assert(icc.valuesAreLessThan([1, 2, 3]) === false);

Method `valuesCompare`

Consumes this and other iterator instances to return Comparison_Results

Parameters

{any|Iterator_Cascade_Callbacks} other - Iterable to compare with this instance of Iterator_Cascade_Callbacks

Returns {Collect_To_Function}

Example

const icc = Iterator_Cascade_Callbacks([1, 2, 3]);

console.log(icc.valuesCompare([1, 2, 4]));
//> '<'

console.log(icc.valuesCompare([1, 2, 2]));
//> '>'

console.log(icc.valuesCompare('123'));
//> '=='

console.log(icc.valuesCompare([1, 2, 3]));
//> '==='

console.log(icc.valuesCompare('spam'));
//> '!=='

Notes

Parameter other that are not type of Iterator_Cascade_Callbacks will be coerced

Custom Interfaces

Descriptions of data structures and generic behaviour

Interface `Callback_Object`

Classy object for storing wrapper function state between iterations

Properties

{Callback_Wrapper} wrapper - Wrapper for callback function that parses inputs and outputs
{Dictionary} storage - Generic dictionary like object

Custom Types

Documentation for custom type definitions

Type `Callback_Function`

Generic callback function for parsing and/or mutating iterator data

Parameters

{any} value - First half of Yielded_Tuple stored in this.value or value from this.iterator.next()
{Index_Or_Key} index_or_key - Either a string or number depending upon iterable type
{Callback_Function_References} references - Dictionary with reference to this Iterator_Cascade_Callbacks and this Callback_Object

Type `Callback_Function_References`

Object with references to Iterator_Cascade_Callbacks and Callback_Object instances

Properties

{Iterator_Cascade_Callbacks} iterator_cascade_callbacks - Instance reference to this of Iterator_Cascade_Callbacks
{Callback_Object} callback_object - Instance reference to this of Callback_Object

Type `Callback_Wrapper`

Wrapper for callback function that parses inputs and outputs

Parameters

{Callback_Object} callback_object - Instance reference to this of Callback_Object
{Iterator_Cascade_Callbacks} iterator_cascade_callbacks - Instance reference to this of Iterator_Cascade_Callbacks

Type `Collect_To_Function`

Callback function for custom collection algorithms

Parameters

{any} target - An object that function will collect values to
{value} any - Value portion of Yielded_Tuple from Iterator_Cascade_Callbacks
{number|string} index_or_key - Index or Key portion of Yielded_Tuple from Iterator_Cascade_Callbacks
{Iterator_Cascade_Callbacks} iterator_cascade_callbacks - Instance reference to this of Iterator_Cascade_Callbacks

Example

const icc = new Iterator_Cascade_Callbacks({ spam: 'flavored', canned: 'ham' });

const map = new Map();

const collection = icc.collectToFunction(map, (target, value) => {
  target.set(index_or_key, value);
});

console.log(collection);
//> Map(2) { 'spam' => 'flavored', 'canned' => 'ham' }

Type `Comparison_Results`

Return string value for comparisons; '==', '===', '!=', '!==', '>=', '>', '<=', or '<'

Notes

== values are equivalent after type coercion
=== values and types are equal
!= values are not equivalent after type coercion
!== values are not equal but types are equivalent
>= left is greater than right and types are equal
> left is greater than right after type coercion
<= left is less than right but types are equivalent
< left is less than right after type coercion

Type `Dictionary`

Generic dictionary like object

Example

const data: Dictionary = { key: 'value' };

Type `Generator_Function_Instance`

Generator function that has not been initialized

Example As Function Parameter

function* gen() { for (let i = 0; i &lt; 10; i++;) { yield i; } }

function collect(generator: Generator_Function_Instance): any[] {
  let collection = [];
  const iterable = generator();
  for (const value of iterable) {
    collection.push(value);
  }
  return collection;
}

Type `Index_Or_Key`

Array index or Object key or Generator count

Example

const key: Index_Or_Key = 'key';
const index: Index_Or_Key = 42;

Type `Yielded_Tuple`

Array with value and index_or_key entries

Example

const result: Yielded_Tuple = ['spam', 3];

Type `Yielded_Result`

Results from Generator/Iterator function/class

Properties

{boolean} done
{any|Yielded_Tuple} value

Example

const icc = new Iterator_Cascade_Callbacks([1, 2, 3]);

let results = icc.next();
while (!results.done) {
  const { value, done } = results;
  console.log('value ->', value, '| done ->', done);

  const [ data, index_or_key ] = value;
  console.log('data ->', data, '| index_or_key ->', index_or_key)

  results = icc.next();
}

Notes

This repository may not be feature complete and/or fully functional, Pull Requests that add features or fix bugs are certainly welcomed.

To Dos

List of unimplemented features and/or undefined behaviour that may be corrected in future versions

Sub-headings within this section will experience much churn; completed items will remain for one minor version after which items, or sections, will be removed from this document. Contributors are encouraged to target incomplete items via Pull Request for merging, or new Git Tag for publishing.

Version `0.0.6`

@types/iterator-cascade-callbacks/iterator-cascade-callbacks.d.ts

Iterator_Cascade_Callbacks - Define static method types in a way that TypeScript understands and produce errors only if used improperly

ts/iterator-cascade-callbacks.ts

Remove /* istanbul ignore next */ comments from source code; currently there are three (3) places that JestJS tests ignores
Add Skip_Iteration, or similar, Error type and refactor skip, and step, methods to throw such error type
zipCompareValues - Fix any usage to utilize the correct type hint of Iterator_Cascade_Callbacks

tsconfig.json

Change _ to true once /* istanbul ignore next */ commits are removed from source
Enable stricter transpiling options

Added strictBindCallApply, strictFunctionTypes, and strictPropertyInitialization configurations

Version `0.0.5`

ts/__tests__/tests-iterator-cascade-callbacks.ts

testsInspect - Sort out why JestJS does not recognize tests as covering lines within inspect_wrapper function.

Fixed by testing ...paramaters within an inspect callback function

Contributing

Options for contributing to iterator-cascade-callbacks and javascript-utilities

Forking

Start making a Fork of this repository to an account that you have write permissions for.

Add remote for fork URL. The URL syntax is git@github.com:<NAME>/<REPO>.git...

cd ~/git/hub/javascript-utilities/iterator-cascade-callbacks

git remote add fork git@github.com:<NAME>/iterator-cascade-callbacks.git

Commit your changes and push to your fork, eg. to fix an issue...

cd ~/git/hub/javascript-utilities/iterator-cascade-callbacks


git commit -F- <<'EOF'
:bug: Fixes #42 Issue


**Edits**


- `<SCRIPT-NAME>` script, fixes some bug reported in issue
EOF


git push fork main

Note, the -u option may be used to set fork as the default remote, eg. git push -u fork main however, this will also default the fork remote for pulling from too! Meaning that pulling updates from origin must be done explicitly, eg. git pull origin main

Then on GitHub submit a Pull Request through the Web-UI, the URL syntax is https://github.com/<NAME>/<REPO>/pull/new/<BRANCH>

Note; to decrease the chances of your Pull Request needing modifications before being accepted, please check the dot-github repository for detailed contributing guidelines.

Sponsor

Thanks for even considering it!

Via Liberapay you may on a repeating basis.

Regardless of if you're able to financially support projects such as iterator-cascade-callbacks that javascript-utilities maintains, please consider sharing projects that are useful with others, because one of the goals of maintaining Open Source repositories is to provide value to the community.

Attribution

License

Iterator that chains callback function execution
Copyright (C) 2021 S0AndS0

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, version 3 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

For further details review full length version of AGPL-3.0 License.

generator iterator library module

@everything-registry/sub-chunk-1940 @zalastax/nolb-ite

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago