nalaka/auto_reset

Ballerina Auto-Reset Watcher

A Ballerina package that automatically monitors file changes and restarts your Ballerina applications during development. This tool helps streamline your development workflow by eliminating the need to manually restart your application every time you make changes to your code.

Features

• 🔍 File Monitoring: Watches for changes in Ballerina files (.bal by default)
• 🚀 Auto-Restart: Automatically restarts your application when changes are detected
• ⚙️ Configurable: Customize watch patterns, ignore paths, and debounce timing
• 📁 Directory Support: Recursively monitors subdirectories
• 🎯 Smart Filtering: Ignores common build directories and files
• 📝 Verbose Logging: Optional detailed logging for debugging

Installation

From Ballerina Central (Recommended)

bal pull nalaka/auto_reset

From Source

1. Clone or download this package
2. Build the package:

   bal build

Quick Start

Basic Usage

Create a simple watcher for your Ballerina project:

import nalaka/auto_reset;

public function main() returns error? {
    auto_reset:WatchConfig config = {
        projectPath: "./",
        ballerinaCmd: "bal run",
        verbose: true
    };
    
    return auto_reset:startWithConfig(config);
}

Advanced Configuration

import nalaka/auto_reset;

public function main() returns error? {
    auto_reset:WatchConfig config = {
        projectPath: "./src",
        watchExtensions: [".bal", ".toml"],
        ignorePaths: ["target/", ".ballerina/", "tests/", ".git/", "docs/"],
        debounceMs: 1000,
        ballerinaCmd: "bal run --offline",
        verbose: true
    };
    
    auto_reset:BallerinaWatcher watcher = auto_reset:createWatcher(config);
    return watcher.startWatching();
}

Configuration Options

Use Cases

1. Web Service Development

Monitor your Ballerina HTTP service and restart automatically:

auto_reset:WatchConfig config = {
    projectPath: "./",
    ballerinaCmd: "bal run service.bal",
    verbose: true,
    debounceMs: 800
};

2. Multi-Module Projects

Watch specific modules or the entire project:

auto_reset:WatchConfig config = {
    projectPath: "./modules/core",
    watchExtensions: [".bal", ".toml"],
    ballerinaCmd: "bal build && bal run target/bin/myapp.jar"
};

3. Integration Testing

Monitor test files and run tests automatically:

auto_reset:WatchConfig config = {
    projectPath: "./tests",
    ballerinaCmd: "bal test",
    ignorePaths: ["target/", ".ballerina/"]
};

API Reference

Types

WatchConfig

Configuration record for the file watcher:

public type WatchConfig record {|
    string projectPath = "./";
    string[] watchExtensions = [".bal"];
    string[] ignorePaths = ["target/", ".ballerina/", "tests/"];
    int debounceMs = 500;
    string ballerinaCmd = "bal run";
    boolean verbose = false;
|};

Functions

startWithConfig(WatchConfig) returns error?

Start watching with a custom configuration.

createWatcher(WatchConfig) returns BallerinaWatcher

Create a watcher instance with custom configuration.

Classes

BallerinaWatcher

Main watcher class with the following methods:

• startWatching() returns error? - Start monitoring files
• stop() returns error? - Stop the watcher and cleanup

Examples

Example 1: Basic HTTP Service Watcher

// watcher.bal
import nalaka/auto_reset;

public function main() returns error? {
    auto_reset:WatchConfig config = {
        ballerinaCmd: "bal run http_service.bal",
        verbose: true
    };
    
    return auto_reset:startWithConfig(config);
}

Example 2: Custom Development Workflow

// dev-watcher.bal
import nalaka/auto_reset;
import ballerina/log;

public function main() returns error? {
    log:printInfo("Starting development watcher...");
    
    auto_reset:WatchConfig config = {
        projectPath: "./src",
        watchExtensions: [".bal", ".json", ".yaml"],
        ignorePaths: ["target/", ".ballerina/", "tests/", "docs/", "*.log"],
        debounceMs: 1000,
        ballerinaCmd: "bal build && bal run target/bin/myapp.jar --config=dev.yaml",
        verbose: true
    };
    
    auto_reset:BallerinaWatcher watcher = auto_reset:createWatcher(config);
    return watcher.startWatching();
}

Best Practices

1. Use Appropriate Debounce Time: Set debounceMs to a reasonable value (500-1000ms) to avoid excessive restarts during rapid file changes.

2. Ignore Build Artifacts: Always include build directories in ignorePaths to prevent infinite restart loops.

3. Specific Watch Extensions: Only watch file types that actually affect your application to reduce unnecessary restarts.

4. Environment-Specific Commands: Use different ballerinaCmd for development vs. production-like testing.

Troubleshooting

Common Issues

Q: The watcher keeps restarting infinitely A: Check your ignorePaths configuration. Make sure to ignore build directories like target/ and .ballerina/.

Q: Changes aren't being detected A: Verify that your file extensions are included in watchExtensions and the files aren't in ignored paths.

Q: The application doesn't start A: Check that your ballerinaCmd is correct and can be executed from the projectPath directory.

Q: Too many restarts happening A: Increase the debounceMs value to allow more time for multiple file changes to settle.

Debug Mode

Enable verbose logging to troubleshoot issues:

auto_reset:WatchConfig config = {
    verbose: true  // Enable detailed logging
};

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License. See the LICENSE file for details.

Changelog

v0.1.0

• Initial release
• Basic file watching functionality
• Configurable watch patterns and ignore paths
• Auto-restart capability
• Verbose logging support

Support

If you encounter any issues or have questions:

1. Check the troubleshooting section above
2. Search existing issues in the repository
3. Create a new issue with detailed information about your problem

Happy coding with auto-restart! 🚀