Iterator

In the ECMAScript specification, an iterator is an object that defines a sequence and, optionally, a return value when the sequence ends. Iterators let you process each item in a collection one at a time, and they include methods to obtain the next item in the collection to process. You can also use different methods depending on whether you want to stop iteration when a specific value or condition is reached.

Some methods in SuiteScript modules return objects that include an iterator. For example, in the N/query module, the Query.run() method runs a query definition and returns a query.ResultSet object. This object includes a method, ResultSet.iterator(), that returns an iterator for the query results. You can use this iterator to process each result in the query result set.

In SuiteScript, you can use iterators in two ways:

• Using the next() Method

• Using the each() Method

Using the next() Method

Iterators in SuiteScript are compatible with the ECMAScript iterator protocol, so you can use the standard ECMAScript next() method to retrieve the next item in an iteration sequence. This method returns an object with two properties:

• value — The next value in the iteration sequence.

• done — A boolean value indicating whether the last value in the iteration sequence has been processed. A value of true indicates that iteration is complete.

The following example shows how to create a simple query using the N/query module and use the next() method to iterate over the query results:

          var myQuery = query.create({
    type: query.Type.CUSTOMER
});

myQuery.columns = [
    myQuery.createColumn({
        fieldId: 'entityid'
    })
];

var results = myQuery.run();

var resultIterator = results.iterator();
var currentResult = resultIterator.next();
while (!currentResult.done) {
    log.debug(currentResult.value);
 
// Do something with the current result
    currentResult = resultIterator.next();
} 

        

For more information about iterators in ECMAScript, see Iterators and generators.

Using the each() Method

The SuiteScript implementation of iterators includes an each() method that you can use to iterate over the items in an iteration sequence. This method accepts a callback function with one parameter, and the function is executed on each item in the iteration sequence. You can return true from this function to retrieve the next item and continue iteration, or you can return false to stop iteration immediately. It can be useful to stop iteration if your script encounters specific data or values and you do not need to retrieve any more items in the collection.

The following example shows how to create a simple query using the N/query module and use the each() method to iterate over the query results:

          var myQuery = query.create({
    type: query.Type.CUSTOMER
});
myQuery.columns = [
    myQuery.createColumn({
        fieldId: 'entityid'
     })
];

var results = myQuery.run();
var resultIterator = results.iterator();

resultIterator.each(function(result) {
    var currentResult = result.value;
    log.debug(currentResult);
 // Do something with the current result
  return true;
}); 

        

Iterator.next()

Method Description	Iterates over the items in the iteration sequence. This method accepts a callback function with one parameter, and the function is executed on each item in the iteration sequence. You can return true from this function to retrieve the next item and continue iteration, or you can return false to stop iteration immediately. It can be useful to stop iteration if your script encounters specific data or values and you do not need to retrieve any more items in the iteration sequence.
Returns	void
Supported Script Types	Client and server scripts For more information, see the help topic SuiteScript 2.x Script Types.
Governance	None
Since	2015.2

Parameters

Parameter	Type	Required / Optional	Description
callback	function	required	A callback function to execute on each item in the iteration sequence.

Syntax

The following code sample shows the syntax for this member. It is not a functional example.

          // Add additional code.
...
// Create or load a query called myQuery
var results = myQuery.run();

var resultIterator = results.iterator();
resultIterator.each(function(result) {
     var currentResult = result.value;
     log.debug(currentResult);
 // Do something with the current result

   return true;
}); 

        

General Notices