🌊 ReFlows

The modern, lightweight task management system that makes background jobs, scheduling, and workflows incredibly simple.

Built for Bun with Node.js compatibility. Zero configuration required.

✨ Why ReFlows?

• 🚀 Zero Configuration - Works out of the box, no setup required
• ⚡ Lightning Fast - Built for Bun with native SQLite integration
• 🗄️ Multi-Database - Bun SQLite, LibSQL, Turso, Cloudflare D1 support
• 🔄 Auto-Sync - Automatic synchronization between databases
• 🌐 Edge-Native - Perfect for Cloudflare Workers and edge computing
• 🔒 Type-Safe - Full TypeScript support with comprehensive types
• 📦 Lightweight - Minimal dependencies, maximum performance
• 🔄 Flexible - Single tasks, batches, schedules, and complex workflows
• 📊 Observable - Built-in monitoring, metrics, and event system
• 🛡️ Production Ready - Error handling, retries, and dead letter queues

🚀 Quick Start

Installation

# For Bun (recommended)
bun add reflows

# For Node.js
npm install reflows @libsql/client

# For Cloudflare Workers
npm install reflows

Your First Task (30 seconds)

import ReFlows from 'reflows';

// Create instance (zero config!)
const reflows = new ReFlows();

// Define what happens when a task runs
reflows.define('send_email', async (task) => {
  const { email, subject } = task.data;
  console.log(`📧 Sending email to ${email}: ${subject}`);

  // Your logic here
  await sendEmail(email, subject);

  return { sent: true };
});

// Start the system
await reflows.start();

// Add a task
await reflows.add('send_email', {
  email: '[email protected]',
  subject: 'Welcome!'
});

console.log('✅ Task added and processing!');

That's it! Your task is now processing in the background.

🎯 What Can You Build?

📧 Email Systems

// Send welcome email series
await reflows.flow('user_onboarding', { userId: 123 }, [
  { type: 'send_welcome', delay: 0 },
  { type: 'send_tutorial', delay: '1 day' },
  { type: 'send_feedback_request', delay: '1 week' }
]);

📊 Data Processing

// Process large datasets in batches
const users = await getUsers();
await reflows.batch('process_user', users, { batchSize: 100 });

⏰ Scheduled Jobs

// Daily reports at 9 AM
await reflows.schedule('daily_report', '0 9 * * *', async () => {
  return { type: 'generate_report', data: { date: new Date() } };
});

🛒 E-commerce Workflows

// Complete order processing pipeline
await reflows.flow('process_order', { orderId }, [
  { type: 'validate_inventory', delay: 0 },
  { type: 'process_payment', delay: '30 seconds' },
  { type: 'send_confirmation', delay: '1 minute' },
  { type: 'notify_warehouse', delay: '5 minutes' }
]);

🗄️ Multi-Database Support

ReFlows supports multiple database adapters with automatic synchronization:

🚀 Auto-Detection (Recommended)

const reflows = new ReFlows({
  storage: {
    adapter: 'auto', // Automatically chooses the best option
    bun: { path: './reflows.db' },
    libsql: { path: './reflows.db' }
  }
});

🌐 Edge Computing (Cloudflare D1)

const reflows = new ReFlows({
  storage: {
    adapter: 'cloudflare-d1',
    d1: {
      accountId: process.env.CLOUDFLARE_ACCOUNT_ID,
      databaseId: process.env.D1_DATABASE_ID,
      apiToken: process.env.CLOUDFLARE_API_TOKEN
    }
  }
});

☁️ Cloud Database (Turso)

const reflows = new ReFlows({
  storage: {
    adapter: 'libsql-remote',
    libsql: {
      url: process.env.TURSO_URL,
      authToken: process.env.TURSO_TOKEN
    }
  }
});

🔄 Hybrid with Sync (Local + Cloud)

const reflows = new ReFlows({
  storage: {
    adapter: 'libsql-local',
    libsql: {
      path: './local.db',
      url: process.env.TURSO_URL,
      authToken: process.env.TURSO_TOKEN
    },
    sync: {
      enabled: true,
      primary: 'libsql-local',    // Fast local operations
      secondary: 'libsql-remote', // Cloud backup
      strategy: 'bidirectional',  // Two-way sync
      interval: 30000             // Sync every 30 seconds
    }
  }
});

📊 Database Comparison

| Database | Environment | Performance | Scalability | Use Case | |----------|-------------|-------------|-------------|----------| | Bun SQLite | Bun | 🚀 Excellent | 🔴 Single Node | Development | | LibSQL Local | Node.js/Bun | ⚡ Very Good | 🔴 Single Node | Production | | LibSQL Remote | Any | ⚡ Good | 🚀 Multi-Region | Distributed | | Cloudflare D1 | Workers | ⚡ Good | 🚀 Global | Edge Computing |

📚 Documentation

🚀 Quick Links

• 📖 Complete Documentation - Full documentation hub
• 🚀 Getting Started Guide - Step-by-step tutorial
• 🗄️ Multi-Database Support - Database adapters & sync
• 🔧 Database Adapters - Detailed adapter guides
• 🔄 Migration Guide - Upgrade from v1.x to v2.x
• 📋 API Reference - Complete API documentation
• 💡 Real-World Examples - Production-ready patterns
• 🎯 Best Practices - Architecture guidelines
• 🔧 Troubleshooting - Common issues & solutions

📖 Quick Reference

| Feature | Method | Documentation | |---------|--------|---------------| | Single Tasks | add() | API Reference | | Batch Processing | batch() | API Reference | | Scheduled Jobs | schedule() | API Reference | | Workflows | flow() | API Reference | | Task Processors | define() | API Reference | | System Status | status() | API Reference |

⚙️ Configuration

ReFlows works with zero configuration by default. For advanced use cases:

const reflows = new ReFlows({
  storage: {
    mode: 'sqlite_only',        // or 'hybrid' for Redis
    database: { path: './tasks.db' }
  },
  workers: {
    default: { concurrency: 5, timeout: 30000 },
    email: { concurrency: 10 },   // High concurrency for emails
    reports: { concurrency: 1 }   // Single report at a time
  }
});

Environment Variables:

REFLOWS_DATABASE_PATH=./tasks.db
REDIS_URL=redis://localhost:6379  # Optional

👉 See complete configuration guide

🚀 Why Choose ReFlows?

⚡ Performance First

• Bun: ~150KB bundle, 1000+ tasks/sec, <300ms cold start
• Node.js: ~2MB bundle, 800+ tasks/sec, <500ms cold start
• SQLite: Embedded database, no external dependencies
• Optional Redis: Scale to millions of tasks

🛠️ Developer Experience

• Zero Config: Works out of the box
• TypeScript: Full type safety and IntelliSense
• Simple API: Intuitive methods, clear documentation
• Flexible: From simple tasks to complex workflows

🏗️ Production Ready

• Reliable: Automatic retries, error handling, dead letter queues
• Observable: Built-in monitoring, metrics, and health checks
• Scalable: Configurable concurrency and worker pools
• Tested: Comprehensive test suite and real-world usage

🔧 Advanced Features

Smart Workflows

await reflows.flow('user_journey', { userId }, [
  { type: 'send_welcome', delay: 0 },
  { type: 'check_engagement', delay: '3 days' },
  {
    type: 'send_followup',
    delay: '1 week',
    condition: async (ctx) => {
      const user = await getUser(ctx.userId);
      return !user.hasLoggedIn;
    }
  }
]);

Powerful Scheduling

// Timezone-aware daily reports
await reflows.schedule('tokyo_report', '0 9 * * *', reportHandler, {
  timezone: 'Asia/Tokyo'
});

// Complex patterns: last Friday of month
await reflows.schedule('month_end', '0 17 * * 5L', monthEndHandler);

Built-in Monitoring

// Listen to events
reflows.on('task:failed', (event) => {
  console.error(`Task ${event.task.id} failed:`, event.error);
});

// Check system health
const status = await reflows.status();
console.log(`Processing ${status.queues.length} queues`);

🧪 Development

Testing

# Run tests
bun test

# Build for production
bun run build

Project Structure

reflows/
├── src/           # Source code
├── docs/          # Documentation
├── examples/      # Example applications
├── test/          # Test files
└── dist/          # Built files

🤝 Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Croner - Excellent cron scheduling library
• Better-SQLite3 - Fast SQLite for Node.js
• Bun - Amazing JavaScript runtime with native SQLite

Ready to get started? 👉 Read the Getting Started Guide

Built with ❤️ for the JavaScript community