Why Choose the cel Flutter Package?

The cel Flutter package brings the Common Expression Language (CEL) to Dart and Flutter, letting you evaluate business rules, feature‑flag conditions, and dynamic filters at runtime without writing a custom parser. It’s lightweight, has no platform dependencies, and works on all Flutter targets.

Tip: Use cel when you need to store rules on a server and let the client evaluate them without a new app release.

When to Use cel

  • Feature‑flag evaluation based on user attributes.
  • Dynamic form validation where rules can change without redeploying.
  • Custom search filters that users can configure.
  • Policy enforcement in multi‑tenant applications.

Installation

Add the package to your pubspec.yaml or run the CLI command:

Code
flutter pub add cel

After the command completes, run flutter pub get to fetch the dependency.

Basic Usage – A Beginner Friendly Example

Below is a minimal, runnable example that demonstrates parsing and evaluating a CEL expression against a Dart map.

Code
import 'package:cel/cel.dart';

void main() {
  // 1️⃣ Define a CEL expression that decides if a user gets a discount.
  const expression =
      'user.age >= 18 && user.country == "US" && purchase.amount > 50';

  // 2️⃣ Parse (compile) the expression.
  final program = CelParser().parse(expression);

  // 3️⃣ Provide input data that matches the expression's variable names.
  final input = {
    'user': {'age': 25, 'country': 'US'},
    'purchase': {'amount': 75}
  };

  // 4️⃣ Evaluate the expression.
  final result = program.evaluate(input);
  print('Eligibility: $result'); // Prints: Eligibility: true
}

This code works out‑of‑the‑box on any Flutter platform (mobile, web, desktop).

Understanding the Steps

  • Expression syntax: CEL uses a simple, C‑like syntax. Strings are double‑quoted, logical operators are && and ||, and you can navigate nested maps with the dot operator.
  • Parsing: CelParser().parse() returns a compiled program that can be reused. If you evaluate the same rule many times, keep the program instance cached.
  • Evaluation: The evaluate method expects a Map that supplies all variables referenced in the expression.

Advanced: Adding Custom Functions

cel ships with the standard CEL function set, but you can extend it with your own Dart functions. This is useful for domain‑specific logic such as checking a user's subscription tier.

Code
import 'package:cel/cel.dart';

// Define a Dart function that matches the CEL signature.
bool isPremiumUser(String tier) => tier == 'gold' || tier == 'platinum';

void main() {
  // Register the custom function.
  final env = CelEnvironment()
    ..addFunction('isPremiumUser', isPremiumUser);

  const expr = 'isPremiumUser(user.tier) && user.age >= 21';
  final program = CelParser(environment: env).parse(expr);

  final data = {
    'user': {'tier': 'gold', 'age': 22}
  };

  final result = program.evaluate(data);
  print('Access granted: $result'); // Prints: Access granted: true
}

Remember to verify the exact API for adding functions in the official docs, as the API may evolve.

Common Mistakes to Avoid

  • Missing variables: If the input map does not contain a variable referenced in the expression, evaluation throws an error. Always validate the input shape or provide default values.
  • Parsing on every frame: Parsing is relatively cheap but not free. Cache the compiled program if you evaluate the same rule repeatedly (e.g., inside a list builder).
  • Assuming UI widgets exist: cel does not provide UI components for rule editing. Pair it with a separate editor if you need a visual rule builder.
  • Using unsupported CEL features: The package follows the CEL spec but may not implement every optional function. Check the pub.dev page for the supported feature list.

Performance Tips

For high‑frequency evaluations (e.g., filtering a large list), consider:

  • Caching the compiled program.
  • Reusing a single CelEnvironment instance for custom functions.
  • Running evaluation in a background isolate if the data set is large.

Conclusion

The cel Flutter package gives you a powerful, declarative way to move business rules out of UI code and into data‑driven expressions. By following the installation steps, using the basic example as a template, and keeping an eye on caching and input validation, you can safely evaluate dynamic rules across all Flutter platforms.

Frequently Asked Questions

What is the cel Flutter package used for?

cel brings the Common Expression Language (CEL) to Dart/Flutter, allowing you to parse and evaluate logical expressions at runtime. It’s ideal for feature‑flag checks, dynamic form validation, custom filters, and policy enforcement.

How do I install the cel package?

Run <code>flutter pub add cel</code> in your project root, then execute <code>flutter pub get</code>. The package has no platform‑specific dependencies.

Can I add my own functions to CEL expressions?

Yes. You can extend the CEL environment with custom Dart functions using <code>CelEnvironment().addFunction()</code>. Refer to the package documentation for the exact API.

Is cel suitable for high‑performance scenarios?

cel is lightweight, but parsing each expression repeatedly adds overhead. Cache the compiled program and reuse a single environment for best performance. For very large data sets, consider evaluating in a background isolate.

Where can I find the full list of supported CEL functions?

The supported function set is documented on the package’s pub.dev page (https://pub.dev/packages/cel). If you need a function that isn’t listed, you can implement it as a custom function.