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

1. Include the waterfall.js script in your HTML file.
2. Initialize the Waterfall instance with optional configuration.
3. 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.

Contributing

Contributions are welcome! If you'd like to contribute, please fork the repository and submit a pull request.

License

Waterfall.js is licensed under the MIT License. See the LICENSE file for more details.

Author

• Piyush Agade (GitHub)

Enjoy building robust workflows with Waterfall.js! 🚀 EOL

echo "README.md created successfully!"