, ], , , )

    -> 

`





$3



A an alternative to Array's .map(..) / .filter(..) / .. methods with ability to

stop the iteration process by throwing STOP or STOP().



`javascript

var {STOP} = require('ig-types/Array')

`



This can be used in two ways:



1) throw as-is to simply stop...

    `javascript

    ;[1,2,3,4,5]

        .smap(function(e){ 

            // simply abort here and now...

            throw STOP })

    `

    Since we aborted the iteration without passing any arguments to STOP,

    .smap(..) will return undefined.



2) throw an instance and return the argument...

    `javascript

    // this will print "4" -- the value passed to STOP...

    console.log([1,2,3,4,5]

        .smap(function(e){ 

            if(e > 3){

              // NOTE: new is optional here...

              //    ...StopIteratiom is an object.js constructor.

              throw new STOP(e) } }))

    `



Note that no partial result is returned unless passed through STOP(..).





#### array.STOP / array.STOP(..)



An _object/constructor_ that if raised (as an exception) while iterating via 

a supporting iterator method will abort further execution and correctly exit.





#### .smap(..) / .sfilter(..) / .sreduce(..) / .sforEach(..)



Like Array's .map(..), .filter(..), .reduce(..) and .forEach(..) but 

with added support for aborting iteration by throwing STOP or STOP().



These can be passed a  callback as an additional last argument 

that will be called if STOP/STOP() is returned or thrown.





$3



Iterating over very large Array instances in JavaScript can block execution,

to avoid this types.js implements .map(..)/.filter(..)/.reduce(..)

equivalent methods that iterate the array in chunks and do it asynchronously 

giving the runtime a chance to run in between.



In the simplest cases these are almost a drop-in replacements for the equivalent

methods but return a promise.

`javascript

var a = [1,2,3,4,5]

    .map(function(e){ 

        return e*2 })



var b

;[1,2,3,4,5]

    .mapChunks(function(e){ 

        return e*2 })

    .then(function(res){

        b = res })



// or with await...

var c = await [1,2,3,4,5]

    .mapChunks(function(e){ 

        return e*2 })

`



These support setting the chunk size (default: 50) as the first argument:

`javascript

var c = await [1,2,3,4,5]

    .mapChunks(2, function(e){ 

        return e*2 })

`



#### array.STOP / array.STOP(..)



Like for .smap(..) and friends iteration 

can be stopped by throwing a array.STOP / array.STOP() and as before 

there are two ways to go:



1) throw as-is to simply stop

    `javascript

    ;[1,2,3,4,5]

        .mapChunks(function(e){ 

            // simply abort here and now...

            throw STOP })

        .catch(function(){

            console.log('done.') })

    `



2) Throw an instance and pass a value to .catch(..)

   `javascript

    ;[1,2,3,4,5]

        .mapChunks(function(e){ 

            if(e > 3){

              // NOTE: new is optional here...

              //    ...StopIteratiom is an object.js constructor.

              throw new STOP(e) } })

        .catch(function(e){

            console.log('first value greater than 3:', e) })

   `





#### .CHUNK_SIZE



The default iteration chunk size.



Note that the smaller this is the more _responsive_ the code is, especially 

in UI applications but there is a small overhead added per chunk.



Default value: 50





#### .mapChunks(..) / .filterChunks(..) / .reduceChunks(..)



The .map(..), .filter(..) and .reduce(..) alternatives respectively:

`bnf

.mapChunks()

.mapChunks(, )

  -> 



(, , )

  -> 

`



`bnf

.filterChunks()

.filterChunks(, )

  -> 



(, , )

  -> 

`



`bnf

.reduceChunks(, )

.mreduceChunks(, , )

  -> 



(, , , )

  -> 

`









All three support chunk handlers in the same way (illustrated on .mapChunks(..)):

`bnf

.mapChunks([, ])

.mapChunks(, [, ])

  -> 



(, , )

  -> 



(, , )

`



The  gets the completed chunk of data after it is computed 

but before the timeout.











Map




`javascript

require('ig-types/Map')

`





$3



Replace key in map retaining item order

`bnf

`



Replace the key without sorting

`bnf

`



Note that when sorting large maps this can get expensive.







$3



Sort