@piyushagade/waterfall NPM

Waterfall.js

Waterfall.js is a lightweight JavaScript library for managing and executing tasks in a sequential or parallel manner. It supports both synchronous and asynchronous task execution, making it ideal for workflows where tasks depend on each other or need to be executed in a specific order.

Installation

You can include Waterfall.js in your project via a CDN:

<script src="https://cdn.jsdelivr.net/npm/@piyushagade/waterfall@latest/waterfall.js"></script>

Alternatively, you can install it using npm:

npm install @piyushagade/waterfall

Usage

Basic Setup

Include the waterfall.js script in your HTML file.
Initialize the Waterfall instance with optional configuration.
Define and execute tasks.

// Initialize Waterfall
const wf = Waterfall({
    options: {
        synchronous: true, // Execute tasks synchronously (default: true)
        verbose: true       // Enable logging (default: false)
    },
    variables: {
        test: "Initial Value" // Shared variables across tasks
    }
});

// Set tasks
wf.setTasks([
    (next, skip, variables, taskId) => {
        console.log("Task 1");
        variables.stage1 = "executed";
        next(); // Proceed to the next task
    },
    (next, skip, variables, taskId) => {
        return new Promise((resolve) => {
            setTimeout(() => {
                console.log("Task 2 (async)");
                variables.stage2 = "executed";
                resolve(); // Proceed to the next task
            }, 2000);
        });
    },
    (next, skip, variables, taskId) => {
        console.log("Task 3");
        variables.stage3 = "executed";
        next(0.5); // Partial progress (pressure)

        setTimeout (() => {
            next(0.5);  // Move to next task when the total pressure is 1
        });
    }
]);

// Execute tasks
wf.executeTasks().then((next, skip, variables, lastTaskId) => {
    console.log("All tasks completed");
    console.log("Final variable:", variables);
});

Key Features

Synchronous and Asynchronous Execution: Tasks can be executed sequentially or in parallel.
Task Management: Add, delete, or modify tasks dynamically.
Shared Variables: Pass and modify variables across tasks.
Progress Control: Use next(fraction) to control task progress or skip() to skip the next task.
Verbose Logging: Enable detailed logging for debugging.

API Reference

`Waterfall(options)`

Initializes a new Waterfall instance.

options (object):
- synchronous (boolean): Whether tasks should execute synchronously (default: true).
- verbose (boolean): Enable verbose logging (default: false).
variables (object): Shared variables accessible across tasks.

`setTasks(tasks)`

Sets an array of tasks to be executed.

tasks (array): An array of functions or promises. Each task receives next, skip, variables, and taskId as arguments.

`addTask(task)`

Adds a single task to the task list.

task (function): A function or promise to be executed.

`deleteTask(id)`

Deletes a task by its ID.

id (string): The ID of the task to delete.

`executeTasks()`

Executes all tasks. Returns a promise that resolves when all tasks are completed.

`setVariables(variables)`

Updates the shared variables.

variables (object): New variables to merge with existing ones.

Example Use Cases

Data Processing: Execute a series of data transformations sequentially.
Workflow Automation: Manage complex workflows with dependencies between tasks.
UI Rendering: Control the rendering order of UI components.