Trough #

Trough is a middleware pipeline library for Dart, inspired by similar libraries in the JavaScript ecosystem. It allows you to create composable function pipelines for processing data in sequence.

Features #

• 🔄 Middleware Pipeline: Create composable function chains
• ⚡ Sync & Async Support: Support for synchronous return values and asynchronous Futures
• 🛡️ Error Handling: Built-in error propagation and handling mechanisms
• 🔗 Method Chaining: Fluent API design
• 📝 Strong Typing: TypeScript-style type definitions
• 🧪 Full Test Coverage: Comprehensive test suite included

Installation #

Add the dependency to your pubspec.yaml file:

dependencies:
  trough: ^1.0.0

Then run:

dart pub get

Quick Start #

Basic Usage #

import 'package:trough/trough.dart';

void main() {
  // Create a new pipeline
  final pipeline = trough();

  // Add middleware - multiply input by 2
  pipeline.use((List<dynamic> input, [Function? next]) {
    final value = input.isNotEmpty ? input[0] as int : 0;
    next?.call(null, [value * 2]);
    return null;
  });

  // Add another middleware - add 10
  pipeline.use((List<dynamic> input, [Function? next]) {
    final value = input.isNotEmpty ? input[0] as int : 0;
    next?.call(null, [value + 10]);
    return null;
  });

  // Run the pipeline
  pipeline.run([5], (Object? error, [List<dynamic>? output]) {
    if (error != null) {
      print('Error: $error');
    } else {
      print('Result: ${output?.first}'); // Output: Result: 20 (5 * 2 + 10)
    }
  });
}

Synchronous Middleware #

void main() {
  final pipeline = trough();
  
  // Synchronous middleware that returns a value directly
  pipeline.use((List<dynamic> input, [Function? next]) {
    final text = input.isNotEmpty ? input[0] as String : '';
    return '$text World!';
  });

  pipeline.run(['Hello'], (Object? error, [List<dynamic>? output]) {
    if (error != null) {
      print('Error: $error');
    } else {
      print('Result: ${output?.first}'); // Output: Result: Hello World!
    }
  });
}

Asynchronous Middleware #

import 'dart:async';

void main() async {
  final pipeline = trough();
  
  // Asynchronous middleware
  pipeline.use((List<dynamic> input, [Function? next]) {
    return Future.delayed(Duration(milliseconds: 100), () {
      final value = input.isNotEmpty ? input[0] as int : 0;
      return value * 3;
    });
  });

  pipeline.run([7], (Object? error, [List<dynamic>? output]) {
    if (error != null) {
      print('Error: $error');
    } else {
      print('Async result: ${output?.first}'); // Output: Async result: 21
    }
  });
}

Error Handling #

void main() {
  final pipeline = trough();
  
  // Middleware that throws an error
  pipeline.use((List<dynamic> input, [Function? next]) {
    if (input.isEmpty) {
      throw Exception('Input cannot be empty');
    }
    next?.call(null, [input[0]]);
    return null;
  });

  pipeline.run([], (Object? error, [List<dynamic>? output]) {
    if (error != null) {
      print('Caught error: $error'); // Output: Caught error: Exception: Input cannot be empty
    } else {
      print('Result: ${output?.first}');
    }
  });
}

API Documentation #

Type Definitions #

Callback

typedef Callback = void Function(Object? error, [List<dynamic>? output]);

Callback function called when the pipeline completes.

Middleware

typedef Middleware = dynamic Function(List<dynamic> input, [Function? next]);

Middleware function signature. Can accept input and an optional next callback function.

Main API #

trough()

Creates a new pipeline instance.

Returns: Pipeline - A new pipeline instance

Pipeline.use(Middleware middleware)

Adds middleware to the pipeline.

Parameters:

• middleware: The middleware function to add

Returns: Pipeline - Returns the pipeline instance for method chaining

Pipeline.run(List<dynamic> values, Callback callback)

Runs all middleware in the pipeline.

Parameters:

• values: Input values passed to the first middleware
• callback: Callback function called when the pipeline completes

wrap(Middleware middleware, Callback callback)

Helper function to wrap middleware with a uniform interface.

Parameters:

• middleware: The middleware function to wrap
• callback: Callback function called on completion

Returns: Function - The wrapped function

Middleware Patterns #

1. Using next Callback #

pipeline.use((List<dynamic> input, [Function? next]) {
  // Process input
  final processed = processInput(input);
  
  // Call next to continue the pipeline
  next?.call(null, [processed]);
  return null;
});

2. Direct Return Value (Synchronous) #

pipeline.use((List<dynamic> input, [Function? next]) {
  final processed = processInput(input);
  return processed; // Return processed value directly
});

3. Return Future (Asynchronous) #

pipeline.use((List<dynamic> input, [Function? next]) {
  return processInputAsync(input); // Return Future
});

4. Error Handling #

pipeline.use((List<dynamic> input, [Function? next]) {
  try {
    final processed = processInput(input);
    next?.call(null, [processed]);
  } catch (error) {
    next?.call(error); // Pass error along
  }
  return null;
});

Real-World Examples #

Text Processing Pipeline #

final textProcessor = trough()
  ..use((List<dynamic> input, [Function? next]) {
    // Trim whitespace
    final text = (input[0] as String).trim();
    next?.call(null, [text]);
    return null;
  })
  ..use((List<dynamic> input, [Function? next]) {
    // Convert to lowercase
    final text = (input[0] as String).toLowerCase();
    next?.call(null, [text]);
    return null;
  })
  ..use((List<dynamic> input, [Function? next]) {
    // Replace special characters
    final text = (input[0] as String).replaceAll(RegExp(r'[^\w\s]'), '');
    next?.call(null, [text]);
    return null;
  });

textProcessor.run(['  Hello, World!  '], (error, output) {
  print(output?.first); // Output: "hello world"
});

Data Validation Pipeline #

final validator = trough()
  ..use((List<dynamic> input, [Function? next]) {
    // Check if input is empty
    if (input.isEmpty || input[0] == null) {
      throw Exception('Input cannot be empty');
    }
    next?.call(null, input);
    return null;
  })
  ..use((List<dynamic> input, [Function? next]) {
    // Check type
    if (input[0] is! String) {
      throw Exception('Input must be a string');
    }
    next?.call(null, input);
    return null;
  })
  ..use((List<dynamic> input, [Function? next]) {
    // Check length
    final text = input[0] as String;
    if (text.length < 3) {
      throw Exception('Input must be at least 3 characters long');
    }
    next?.call(null, ['Validation passed: $text']);
    return null;
  });

Development #

Run Tests #

dart test

Run Example #

dart run example/trough_example.dart

Code Formatting #

dart format .

Static Analysis #

dart analyze

License #

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

Contributing #

Contributions are welcome! Please feel free to submit Pull Requests or create Issues.

Related Projects #

• trough (JavaScript) - The original JavaScript version
• unified - Text processing ecosystem that uses trough

Note: This library's design is inspired by similar libraries in the JavaScript ecosystem, particularly wooorm/trough.