# 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:

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

Alternatively, you can install it using npm:

```bash
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.

```javascript
// 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](https://github.com/piyushagade/waterfall/blob/main/LICENSE) file for more details.

### Author

- Piyush Agade ([GitHub](https://github.com/piyushagade))

---

Enjoy building robust workflows with Waterfall.js! 🚀
EOL

echo "README.md created successfully!"