controlled-loop

controlled-loop

Methods

(static) next(…paramsopt) → {ReturnValue|controlled-loop}

See:

Moves forward in the data and runs the controller on the key/value pair. If the instance is not paused or if the number of iterations has been set, next() will continue to call itself until it hits the end of the data, the instance is paused, or the number of called iterations have been processed

Parameters:
Name Type Attributes Description
params * <optional>
<repeatable>

additional parameters to pass to the controller
Returns:
Type
ReturnValue | controlled-loop

(static) previous(…paramsopt) → {ReturnValue}

See:

Moves backwards in the data and runs the controller on the key/value pair. If the instance is not paused or if the number of iterations has been set, previous() will continue to call itself until it hits the end of the data, the instance is paused, or the number of called iterations have been processed

NOTE: previous() is NOT the same thing as using reverse() or moving from the opposite end. It is moving one increment in the opposite direction as next() from the current location.

Parameters:
Name Type Attributes Description
params * <optional>
<repeatable>

additional parameters to pass to the controller
Returns:
Type
ReturnValue

(static) repeat(…paramsopt) → {ReturnValue}

Calls the controller at the current position in the data

Parameters:
Name Type Attributes Description
params * <optional>
<repeatable>

additional parameters to pass to the controller
Returns:
Type
ReturnValue

(static) run(countopt, …paramsopt) → {Object}

See:

Loops through the data without stopping (like a forEach()).
The equivalent of calling loop.pause(false).next().
NOTE: The controller function can call pause() at any time to return to normal incremental processing.

If the parameter count is added, the loop will run count times instead of continuously

Example
var myArray = [1,2,3,4,5,6,7,8,9,10];
 var loop=controlledLoop(myArray);
 loop.run(3);
 // is equivalent to
 loop.next().next().next();
Parameters:
Name Type Attributes Description
count number <optional>

if count is passed, next() will be called for this many iterations. Pass null/false or a number <1 to run fully while passing parameters.
params * <optional>
<repeatable>

additional parameters to pass to the controller
Returns:
Type
Object

(static) runBack(countopt, …paramsopt) → {Object}

See:

Loops through the data without stopping (like a forEach()).
The equivalent of calling loop.pause(false).previous().
NOTE: The controller function can call pause() at any time to return to normal incremental processing.

If the parameter count is added, the loop will run count times instead of continuously

Example
var myArray = [1,2,3,4,5,6,7,8,9,10];
 var loop=controlledLoop(myArray);
 loop.runBack(3);
 // is equivalent to
 loop.previous().previous().previous();
Parameters:
Name Type Attributes Description
count number <optional>

if count is passed, previous() will be called for this many iterations. Pass null or a number <1 to run fully while passing parameters.
params * <optional>
<repeatable>

additional parameters to pass to the controller
Returns:
Type
Object

(static) reverse(optionsopt) → {controlled-loop}

Reverses the direction the position is moving within the data

Parameters:
Name Type Attributes Default Description
options object <optional>
 {reset:false, clear:false, position:-1}

Whether to reset back to the beginning of the data or to the specified position and whether to clear the values. All 3 properties are optional.
Returns:
Type
controlled-loop

(static) reset(clearopt, positionopt) → {controlled-loop}

Returns the position back to the StartAt or the specified position and optionally clears the values.

Parameters:
Name Type Attributes Description
clear boolean <optional>

whether to clear the values
position startAtNumber <optional>

The position to reset to. This overrides but does not update the StartAt option. Any position that is out of bounds (<0 or >keys.length-1) will be ignored.
Returns:
Type
controlled-loop

(static) skip(steps, execute, …paramsopt) → {controlled-loop|ReturnValue}

Skips over a certain number of keys without processing.
If you try to skip out-of-bounds, it will stop at the appropriate end (0 or length-1).

Parameters:
Name Type Attributes Description
steps number

the number of increments to skip. The value can be negative to skip backwards.
execute boolean

whether to run repeat() when done moving.
params * <optional>
<repeatable>

if execute, the additional data to pass to repeat()
Returns:
  • if executed, it returns the result, otherwise it returns the loop object
Type
controlled-loop | ReturnValue

(static) gotoKey(key, execute, …paramsopt) → {controlled-loop|ReturnValue}

See:

Looks up a specified key and moves the position to that index.

NOTE: If the key does not exist, it returns the out-of-bounds object and does not move the position.

Parameters:
Name Type Attributes Description
key number | string

The key to look for
execute boolean

whether to run repeat() when done moving.
params * <optional>
<repeatable>

if execute, the additional data to pass to repeat()
Returns:
  • if executed, it returns the result, otherwise it returns the loop object
Type
controlled-loop | ReturnValue

(static) setOptions(opt, value) → {controlled-loop}

See:

Resets one or more options for the loop. Options can either be a name/value pair or an object with multiple properties.

The following are the properties that can be set

1. increment
2. startAt
3. apply
4. target
5. controller
Example
var loop=controlledLoop(data)
 loop.setOptions("increment",3);
 // sets the increment property to 3

 loop.setOptions({"increment":3, "startAt":2});
 // sets the increment property to 3 and the startAt property to 2
Parameters:
Name Type Description
opt string | object

Either the name of the property to set or an object with multiple properties
value

The value to set if the first parameter is of type string.
Returns:
Type
controlled-loop

(static) isComplete(previous) → {boolean}

See:

Returns true if you can no longer move forward in the data by the increment amount (same as the done property in returns)

Parameters:
Name Type Description
previous boolean

Whether to calculate as 'backwardinstead offorward. (same as thedonep` property in returns)
Returns:
Type
boolean

(static) pause(stateopt) → {controlled-loop}

Toggles the current paused state

Parameters:
Name Type Attributes Description
state boolean <optional>

If a value is passed, the paused state will be set to that value
Returns:
Type
controlled-loop

(static) getValues(asObjectopt) → {array|object}

Gets an array of values that have been returned by the 'controller'.

Parameters:
Name Type Attributes Description
asObject boolean <optional>

Return an Object of key/return values instead of an array
Returns:
Type
array | object

(static) getValue(key, asObjectopt) → {*}

Gets the value of a single key that has been returned by the 'controller'.

Parameters:
Name Type Attributes Description
key string | number

the key which you want the processed value for
asObject boolean <optional>

Return as an object
Returns:
  • either the processed value for the key or if asObject {key:value}
Type
*

(static) clearValues() → {controlled-loop}

Clears the values of the loop

Returns:
Type
controlled-loop

(static) status() → {Status}

See:

Gets the status of the loop

Returns:
Type
Status

(static) getLastReturn() → {ReturnValue}

Returns the last return from running the controller.
If multiple increments have been executed (such as using run()), this will still return the last value generated.

Returns:
Type
ReturnValue

(static) defer() → {function}

Creates a function that can be called within a Promise which will correctly store the value. The defered function takes a single paramter, the value to be stored, and will then return a ReturnValue the same as any other call.

To use within your callback, assign loop.defer() before your Promise call, then when your Promise returns, call the defered function with the value you wish you assign.

Example
// looping through an array of URLs one at a time
 var loop=controlledLoop(data,function(val,key,loopObj){
		var cb=loopObj.defer();
		$http.get(val,function(result){
				cb(result.data);
				loopObj.next();
		});
	});
Returns:
Type
function