npm package: @gov.nasa.jpl.honeycomb/scheduling-utilities
Description: Utilities for scheduling asynchronous tasks.
Latest version: 0.0.6

# scheduling-utilities

Set of packages for scheduling tasks (debounced or otherwise) in a specific order during a frame.

<!--{package-dependencies ./package.json}-->

# Use

## Scheduler
```js
import { Scheduler } from '@gov.nasa.jpl.honeycomb/scheduling-utilities';

Scheduler.schedule( () => console.log('end of frame!'), 1000 );

Scheduler.scheduleNextFrame( () => console.log('end of next frame!'), 1000 );
```

## Debouncer
```js
import { Debouncer } from '@gov.nasa.jpl.honeycomb/scheduling-utilities';

const debouncer = new Debouncer();
for ( let i = 0; i < 100; i ++ ) {

    debouncer.run( 'task', () => console.log( 'runs once!' ) );

}

// "runs once!" is logged once
```

## JobRunner

# API

<!-- START_AUTOGENERATED_DOCS -->
## Constants
```
BEFORE_ALL_PRIORITY = -Infinity
MOUSE_EVENT_PRIORITY = 1000
RENDER_PRIORITY = 2000
UI_UPDATE_PRIORITY = 3000
AFTER_ALL_PRIORITY = Infinity
```

## Functions
### enqueueMicrotask<a name="enqueueMicrotask"></a>

```js
enqueueMicrotask( func : Function ) : void
```

Enqueues a function to be run after everything this frame but before the start
of the next frame using `Promise.resolve`.

See this document on [microtasks](https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API/Microtask_guide).

## Debouncer

Reusable class instance for defining, tracking, and flushing tasks that
are debounced to run at the end of frame. Uses [Scheduler](#Scheduler) to
schedule tasks.

### run<a name="Debouncer#run"></a>

```js
run( name : String, func : Function, priority : Number = 0 ) : void
```

Creates a task to be run at the end of frame with the unique key `name`. If a
task with the given name is already scheduled it will be cancelled in favor
of the new one.

Priority corresponds to the priority concept used in [Scheduler](#Scheduler).

### flush<a name="Debouncer#flush"></a>

```js
flush( name : String ) : Boolean
```

Flushes the task with the given name and runs it now.

Returns true of the task existed.

### flushAll<a name="Debouncer#flushAll"></a>

```js
flushAll(  ) : void
```

Flushes every scheduled task.

### cancel<a name="Debouncer#cancel"></a>

```js
cancel( name : String ) : Boolean
```

Cancels the task with the given name.

Returns true of the task existed.

### cancelAll<a name="Debouncer#cancelAll"></a>

```js
cancelAll(  ) : void
```

Cancels every scheduled task.

## JobRunner

Utility for enqueing an optionally cancelable, asynchronous task that you only want
to perform a few of at a time, such as file reads, http requests, etc. Only a certain
number of jobs will be actively running at once. Once a job completes more will start.

### maxJobs<a name="JobRunner#maxJobs"></a>

```js
maxJobs : Number = 10
```


The maximum number of jobs that can be run at once.


### run<a name="JobRunner#run"></a>

```js
run( func : Function, cancel : Function = null ) : Promise
```

Enqueues a task to be run. If there are fewer then [maxJobs](#.maxJobs) running then the task will
be run immediately. The returned promise includes a `cancel` function on it which can be used to
remove the task from the job queue. If a task is cancelled then the `cancel` callback passed into
the function will be called only if the task has already begun running.

## Coroutine

Class for running a coroutine over multiple frames using a generator.

### running<a name="Coroutine#running"></a>

```js
running : Boolean
```


Getter indicating whether or not the coroutine is currently running.


### priority<a name="Coroutine#priority"></a>

```js
priority : Number = 0
```


Field indicating the order to run the task with in the scheduler. Smaller numbers
are run first.


### constructor

```js
constructor( task : Generator, cancel : Function | null = null ) : void
```

Takes a generator function "task" to run over multiple frames and an optional
"cancel" function which will run if the coroutine is cancelled mid run.

### run<a name="Coroutine#run"></a>

```js
run( args : ...any ) : void
```

Runs the coroutine. Any arguments passed to this function are passed into the task
function. Throws an error if a task is already runninig.

### cancel<a name="Coroutine#cancel"></a>

```js
cancel(  ) : Boolean
```

Cancels the current running task if there is one and returns true if a task was running.

## CancellablePromiseTask

### cancel<a name="CancellablePromiseTask#cancel"></a>

```js
cancel : Function
```


Cancel the current ask and remove it from the queue so it's not run.


### flush<a name="CancellablePromiseTask#flush"></a>

```js
flush : Function
```


Run the task now and remove it from the queue.


## Scheduler

Class for scheduling events with a priority order before the end
of the frame. If the queue of events has already been run this frame
they are scheduled for the next frame. A singleton of this class is
exported as `Scheduler` from the package.

The Scheduler runs a consistent loop in the background that runs tasks
every frame or every 500ms, which ever comes first.

### flush<a name="Scheduler#flush"></a>

```js
flush(  ) : void
```

Run all tasks in the queue.

### schedule<a name="Scheduler#schedule"></a>

```js
schedule( func : Function, priority : Number = 0 ) : CancellablePromiseTask
```

Schedules a task to be run when the next flush of tasks is scheduled to run, which is often at the
end of the current frame. If they cannot be run at the end of the current frame or the queue of tasks
has already been flushed then the task will be run next frame.

Priority indicates the order in which functions will get run. So a task with a priority of `0` will
get run first while one with a priority of `100` will get run last. If a called task adds a callback
to the queue it will get added and run to the queue that is currently being flushed, meaning it will
get called before the current frame ends.

### scheduleNextFrame<a name="Scheduler#scheduleNextFrame"></a>

```js
scheduleNextFrame( func : Function, priority : Number = 0 ) : CancellablePromiseTask
```

Like [schedule](#Scheduler#schedule) but queues a task to get run next frame along with other tasks
that need to get run.


<!-- END_AUTOGENERATED_DOCS -->