idle-iterator v1.1.0

• Why does this project exist?
• Installation
• Polyfill
• Examples
  • Basic
  • Cancel Iterate
• Array Examples
  • Basic
  • Cancel Iterate
• API List
  • IdleIterator
  • IdleArray
• License

Why does this project exist?

Idle Iterator provide the solution that we can iterate the iterator(such as Array) when the browser is idle.

It means that iteration wont get in the user’s way. In fact, web apps often become unresponsive when iterate large data.

The magic of Idle Iterator is requestIdleCallback, you can find more detail here.

Installation

Idle Iterator only support for browser environment!

npm install idle-iterator

// or yarn
yarn add idle-iterator

Polyfill

requestIdleCallback is an experimental technology, please import polyfill before using:

// provide window.requestIdleCallback and window.cancelIdleCallback
import 'idle-iterator/dist/polyfills';

Examples

Basic

import { IdleIterator } from 'idle-iterator';

const idleIterator = new IdleIterator();
const myMap = new Map([
  ['key1', 'value1'],
  ['key2', 'value2'],
  // ...
]);
function callback(element, index) {
  console.log(element, index, this);
}

const result = await idleIterator.forOf(myMap, callback, 'this');
// output
// ["key1", "value1"] 0 'this'
// ["key2", "value2"] 1 'this'
// ...

console.log(result); // result is tuple that first element is function return value, and the second is flag that represent whether iteration is complete
// output
// [null, true]

Cancel Iterate

import { IdleIterator } from 'idle-iterator';

const idleIterator = new IdleIterator();
const myMap = new Map([
  ['key1', 'value1'],
  ['key2', 'value2'],
  // ...
]);

1. Use stop method in callback.

   The method will cancel next iterate.

const result = await idleIterator.forOf(myMap, (element, index, stop) => {
  console.log(element, index);
  stop();
});
// output
// ["key1", "value1"] 0

console.log(result);
// output
// [null, false]

2. Use cancelIterate method.

   The method will cancel requestIdleCallback callback if iteration not complete.

const promise = idleIterator.forOf(myMap, callback).cancelIterate();
promise.cancelIterate();
// there no output

3. Use cancelAllIterate method.

   The method will cancel all requestIdleCallback callback if iteration not complete.

idleIterator.forOf(myMap, callback);
idleIterator.cancelAllIterate();
// there no output

Array Examples

Idle Iterator also support Array methods.

Basic

import { IdleIterator } from 'idle-iterator';

const idleIterator = new IdleIterator();
const myArray = [
  1, 2, 3, 4,
  // ...
];

const result = await idleIterator.array(myArray).every(() => true);

console.log(result);
// output
// [true, true]

Cancel Iterate

1. Use stop method in callback.

const result = await idleIterator.array(myArray).every((value, index, array, stop) => {
  console.log(element);
  if (element === 1) {
    stop();
  }
  return true;
});
// output
// 1

console.log(result);
// output
// [true, false]

2. Use cancelIterate method.

const promise = idleIterator.array(myArray).every(() => true);
promise.cancelIterate();
// there no output

3. Use cancelAllIterate method.

idleIterator.array(myArray).every(() => true);
idleIterator.cancelAllIterate();
// there no output

Reference to IdleArray for more details about idleIterator.array.

Note: The iteration return Promise, if you codes depend on the result of iteration, await iteration complete.

API List

All of methods of iteration return CancelPromise.

interface CancelPromise<T> extends Promise<T> {
  cancelIterate: () => void;
}

IdleIterator

IdleArray

IdleArray achieve all methods that Array use iteration.

All methods's parameters is same as Array, just add stop method at end of callback's parameters.

Such as every:

type every<T> = (
  callbackFn: (value: T, index: number, array: T[], stop: () => void) => unknown,
  thisArg?: unknown
) => CancelPromise<[ReturnType<T[]['every']>, boolen]>;

Support methods:

• every
• filter
• find
• findIndex
• forEach
• map
• some

License

MIT