Class TaskGroup

Defined in: src/lib/taskgroup.coffee
Inherits: Interface

Overview

Public: Our TaskGroup class. Available configuration is documented in ::setConfig. Available events: - `started()` - emitted when we start execution - `running()` - emitted when the first item starts execution - `failed(err)` - emitted when execution exited with a failure - `passed()` - emitted when execution exited with a success - `completed(err, results)` - emitted when execution exited, `results` is an Array of the result arguments for each item that executed - `error(err)` - emtited if an unexpected error occured within ourself - `done(err, results)` - emitted when either the execution completes (the `completed` event) or when an unexpected error occurs (the `error` event) - `item.*(...)` - bubbled events from an added item - `task.*(...)` - bubbled events from an added Task - `group.*(...)` - bubbled events from an added TaskGroup Available internal statuses: - `null` - execution has not yet started - `'started'` - execution has begun - `'running'` - execution of items has begun - `'failed'` - execution has exited with failure status - `'passed'` - execution has exited with success status - `'destroyed'` - we've been destroyed and can no longer execute

Class Method Summary

Instance Method Summary

Inherited Method Summary

Methods inherited from Interface

.whenDone, .onceDone, .done, .getNames, .getName, .getConfig

Class Method Details

TaskGroup .create(args...) Source

Public: Creates a new TaskGroup instance. args - The Arguments to be forwarded along to the ::constructor. Returns the new TaskGroup instance.

Parameters:

  • argsThe Arguments to be forwarded along to the ::constructor.

Returns:

Boolean .isTaskGroup(group) Source

Public: A helper method to check if the passed argument is an instanceof a TaskGroup. item - The possible instance of the TaskGroup that we want to check Returns a Boolean of whether or not the item is a TaskGroup instance.

Parameters:

  • (TaskGroup) itemThe possible instance of the TaskGroup that we want to check

Returns:

  • (Boolean) — Returns a Boolean of whether or not the item is a TaskGroup instance.

Constructor Details

::constructor(args...) Source

Public: Initialize our new TaskGroup instance. Forwards Arguments onto ::setConfig.

Instance Method Details

::addGroup(args...) Source

Public: Add a TaskGroup with some configuration to ourself, create it if needed. args - Arguments to configure (and if needed, create) the TaskGroup

Parameters:

  • (TaskGroup) argsArguments to configure (and if needed, create) the TaskGroup

::addGroups(items, args...) Source

Public: Add TaskGroups with some configuration to ourself, create it if needed. items - An Array of TaskGroup items to add to ourself args - Optional Arguments to configure each added TaskGroup

Parameters:

  • (Array) itemsAn Array of TaskGroup items to add to ourself
  • (TaskGroup) argsOptional Arguments to configure each added TaskGroup

::addTask(args...) Source

Public: Add a Task with some configuration to ourself, create it if needed. args - Arguments to configure (and if needed, create) the task

Parameters:

  • argsArguments to configure (and if needed, create) the task

::addTasks(items, args...) Source

Public: Add Tasks with some configuration to ourself, create it if needed. items - An Array of Task items to add to ourself args - Optional Arguments to configure each added Task

Parameters:

  • (Array) itemsAn Array of Task items to add to ourself
  • (Task) argsOptional Arguments to configure each added Task

::clear() Source

Public: Clear remaning items.

TaskGroup ::createGroup(args...) Source

Public: Create a TaskGroup instance from some configuration. If the first argument is already a TaskGroup instance, then just update it's configuration with the remaning arguments. args - Arguments to use to configure the TaskGroup instance Returns the new TaskGroup instance

Parameters:

  • (TaskGroup) argsArguments to use to configure the TaskGroup instance

Returns:

Task ::createTask(args...) Source

Public: Create a Task instance from some configuration. If the first argument is already a Task instance, then just update it's configuration with the remaning arguments. args - Arguments to use to configure the Task instance Returns the new Task instance

Parameters:

  • (Task) argsArguments to use to configure the Task instance

Returns:

  • (Task) — Returns the new Task instance

::destroy() Source

Public: Destroy all remaining items and remove listeners.

Object ::getItemNames() Source

Public: Gets the names of the items, the total number of items, and their results for the purpose of debugging. Returns an Object containg the hashes: :remaining - An Array of the names of the remaining items :running - An Array of the names of the running items :completed - An Array of the names of the completed items :total - A Number of the total items we have :results - An Array of the results of the compelted items

Returns:

  • (Object) — Returns an Object containg the hashes:
    • (Array) remainingAn Array of the names of the remaining items
    • (Array) runningAn Array of the names of the running items
    • (Array) completedAn Array of the names of the completed items
    • (Number) totalA Number of the total items we have
    • (Array) resultsAn Array of the results of the compelted items

Object ::getItemTotals() Source

Public: Gets the total number count of each of our item lists. Returns an Object containg the hashes: :remaining - A Number of the total remaining items :running - A Number of the total running items :completed - A Number of the total completed items :total - A Number of the total items we have :results - A Number of the total results we have

Returns:

  • (Object) — Returns an Object containg the hashes:
    • (Number) remainingA Number of the total remaining items
    • (Number) runningA Number of the total running items
    • (Number) completedA Number of the total completed items
    • (Number) totalA Number of the total items we have
    • (Number) resultsA Number of the total results we have

Number ::getItemsTotal() Source

Public: Gets the total number of items Returns a Number of the total items we have

Returns:

  • (Number) — Returns a Number of the total items we have

Boolean ::hasExited() Source

Public: Have we finished its execution yet? Returns a Boolean which is `true` if we have finished execution

Returns:

  • (Boolean) — Returns a Boolean which is true if we have finished execution

Boolean ::hasItems() Source

Public: Whether or not we have any items Returns a Boolean which is `true` if we have any running or remaining items

Returns:

  • (Boolean) — Returns a Boolean which is true if we have any running or remaining items

Boolean ::hasRemaining() Source

Public: Whether or not we have any items that are yet to execute Returns a Boolean which is `true` if we have any items that are still yet to be executed

Returns:

  • (Boolean) — Returns a Boolean which is true if we have any items that are still yet to be executed

Boolean ::hasRunning() Source

Public: Whether or not we have any running items Returns a Boolean which is `true` if we have any items that are currently running

Returns:

  • (Boolean) — Returns a Boolean which is true if we have any items that are currently running

Boolean ::hasStarted() Source

Public: Have we started execution yet? Returns a Boolean which is `true` if we have commenced execution

Returns:

  • (Boolean) — Returns a Boolean which is true if we have commenced execution

Boolean ::isComplete() Source

Public: Have we completed its execution yet? Completion of executed is determined of whether or not we have started, and whether or not we are currently paused or have no remaining and running items left Returns a Boolean which is `true` if we have completed execution

Returns:

  • (Boolean) — Returns a Boolean which is true if we have completed execution

Boolean ::isEmpty() Source

Public: Whether or not we have no items left Returns a Boolean which is `true` if we have no more running or remaining items

Returns:

  • (Boolean) — Returns a Boolean which is true if we have no more running or remaining items

::onceDone(handler) Source

Public: Once Done Promise. Fires the listener once, either on the next tick if we are already done, or if not, once the `done` event fires. listener - The Function to attach or execute.

Parameters:

  • (Function) listenerThe Function to attach or execute.

::run(args...) Source

Public: Start the execution.

::setConfig(opts = {}) Source

Public: Set the configuration for our instance. Despite accepting an Object of configuration, we can also accept an Array of configuration. When using an array, a String becomes the :name, a Function becomes the :method, and an Object becomes the :config config - Our configuration Object can contain the following fields: :name - (default: null) A String for what we would like our name to be, useful for debugging. :done - (default: null) A Function that we would like passed to ::onceDone (aliases are :onceDone, and :next) :whenDone - (default: null) A Function that we would like passed to ::whenDone :on - (default: null) An Object of (eventName => listener) that we would like bound via EventEmitter.on. :once - (default: null) An Object of (eventName => listener) that we would like bound via EventEmitter.once. # :method - (default: null) A Function that we would like to use to created nested groups and tasks using an inline style. :parent - (default: null) A parent TaskGroup that we may be attached to. :onError - (default: 'exit') A String that is either `'exit'` or `'ignore'`, when `'ignore'` errors that occur within items will not halt execution and will not be reported in the completion callbacks `err` argument (but will still be in the `results` argument). :concurrency - (default: 1) The Number of items that we would like to execute at the same time. Use `0` for unlimited. `1` accomplishes serial execution, everything else accomplishes parallel execution. :run - (default: true) A Boolean for whether or not to the :method (if specified) automatically. :nestedConfig - (default: null) An Object of nested configuration to be applied to all items of this group. :nestedTaskConfig - (default: null) An Object of nested configuration to be applied to all Tasks of this group. :tasks - (default: null) An Array of tasks to be added as children. :groups - (default: null) An Array of groups to be added as children. :items - (default: null) An Array of Task and/or TaskGroup instances to be added to this group. :sync - (default: false) A Boolean for whether or not we should execute certain calls asynchronously (`false`) or synchronously (`true`)

Parameters:

  • (Object) configOur configuration Object can contain the following fields:
    • (String) name(default: null) A String for what we would like our name to be, useful for debugging.
    • (Function) done(default: null) A Function that we would like passed to ::onceDone (aliases are :onceDone, and :next)
    • (Function) whenDone(default: null) A Function that we would like passed to ::whenDone
    • (Object) on(default: null) An Object of (eventName => listener) that we would like bound via EventEmitter.on.
    • (Object) once(default: null) An Object of (eventName => listener) that we would like bound via EventEmitter.once. # :method
    • (TaskGroup) parent(default: null) A parent TaskGroup that we may be attached to.
    • (String) onError(default: 'exit') A String that is either 'exit' or 'ignore', when 'ignore' errors that occur within items will not halt execution and will not be reported in the completion callbacks err argument (but will still be in the results argument).
    • (Number) concurrency(default: 1) The Number of items that we would like to execute at the same time. Use 0 for unlimited. 1 accomplishes serial execution, everything else accomplishes parallel execution.
    • (Boolean) run(default: true) A Boolean for whether or not to the :method (if specified) automatically.
    • (Object) nestedConfig(default: null) An Object of nested configuration to be applied to all items of this group.
    • (Object) nestedTaskConfig(default: null) An Object of nested configuration to be applied to all Tasks of this group.
    • (Array) tasks(default: null) An Array of tasks to be added as children.
    • (Array) groups(default: null) An Array of groups to be added as children.
    • (Array) items(default: null) An Array of Task and/or TaskGroup instances to be added to this group.
    • (Boolean) sync(default: false) A Boolean for whether or not we should execute certain calls asynchronously (false) or synchronously (true)

::setNestedConfig(config = {}) Source

Public: Set Nested Config

::setNestedTaskConfig(config = {}) Source

Public: Set Nested Task Config

::whenDone(handler) Source

Public: When Done Promise. Fires the listener, either on the next tick if we are already done, or if not, each time the `done` event fires. listener - The Function to attach or execute.

Parameters:

  • (Function) listenerThe Function to attach or execute.