Iterator Cascade Callbacks

Iterator that chains callback function execution

---

• ⬆ Top of Document

• 🏗 Requirements

• ⚡ Quick Start

  • 📝 Edit Your ReadMe File
  • 💾 Commit and Push

• 🧰 Usage

  • NodeJS Examples
  • Web Application Example

• 🔣 API

  • Class Stop_Iteration

    • Method Stop_Iteration.constructor

  • Class Pause_Iteration

    • Method Pause_Iteration.constructor

  • Class Callback_Object

    • Method Callback_Object.constructor
    • Method Callback_Object.call

  • Class Iterator_Cascade_Callbacks

    • Method Iterator_Cascade_Callbacks.constructor
    • Static Method *iteratorFromArray
    • Static Method *iteratorFromObject
    • Static Method *iteratorFromGenerator
    • Static Method compareValues
    • Static Method zip
    • Static Method zipCompareValues
    • Static Method zipValues
    • Method *iterateCallbackObjects
    • Method collect
    • Method collectToArray
    • Method collectToFunction
    • Method collectToObject
    • Method filter
    • Method forEach
    • Method inspect
    • Method limit
    • Method map
    • Method next
    • Method skip
    • Method step
    • Method take
    • Method valuesAreEqual
    • Method valuesAreGreaterOrEqual
    • Method valuesAreGreaterThan
    • Method valuesAreLessOrEqual
    • Method valuesAreLessThan
    • Method valuesCompare

  • Custom Interfaces

    • Interface Callback_Object

  • Custom Types

    • Type Callback_Function
    • Type Callback_Function_References
    • Type Callback_Wrapper
    • Type Collect_To_Function
    • Type Comparison_Results
    • Type Dictionary
    • Type Generator_Function_Instance
    • Type Index_Or_Key
    • Type Yielded_Tuple
    • Type Yielded_Result

• 🗒 Notes

• ✔ To Dos

  • Version 0.0.6
  • Version 0.0.5

• 📈 Contributing

  • 🔱 Forking
  • 💱 Sponsor

• 📇 Attribution

• ⚖ Licensing

---

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

🎉 Excellent 🎉 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 < 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

• [X] Enable stricter transpiling options

Added strictBindCallApply, strictFunctionTypes, and strictPropertyInitialization configurations

---

Version 0.0.5

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

• [X] 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 [e-mail]:<NAME>/<REPO>.git...

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

git remote add fork [e-mail]:<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

• GitHub -- github-utilities/make-readme

• Dev IO -- Iterators in Typescript

• GitHub -- Microsoft/TypeScript -- Issue 3841 -- T.constructor should be of type T

• geekAbyte -- Typeing Iterables and Iterators with TypeScript

• Medium -- How to chain functions in JavaScript

• Mozilla Developer Network -- Iterators and Generators

• StackOverflow -- check if function is a generator

• StackOverflow -- Checking whether something is iterable

• StackOverflow -- Interfaces with construct signatures not type checking

• StackOverflow -- How can I add new line/linebreak character in title attribute in HTML

---

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.