Add enhanced API for Drules with dynamic fact management and action chaining

[kasutu]

Introduce an enhanced API for Drules that supports dynamic fact management and action chaining, along with integration tests to validate various rule evaluations. This update enhances the OOP-friendliness and type safety of the API, making it suitable for modern Dart and Flutter applications.

closes #8

[anidotnet]

It would be prudent to mention this new feature at the very top of the README file also, where it defines what is drules. Also append the Feature section with the new features and similarly append the Usage section and add your fluent api usage there. My suggestion here would be to properly integrate the documentation of your changes into the existing sections and add new section if required.

[anidotnet]

Could you please add tests for remaining logical operators, edge cases and error scenarios as well?

[anidotnet]

Could you please change the file name to something like - fluent_api.dart?

[anidotnet]

Can we not integrate this fluent api into the existing RuleEngine class and leverage features like activation event subscription etc.?

[anidotnet]

Change this file name accordingly with the new name of the file drules_enhanced.dart.

[anidotnet]

First of all many thanks for your first contribution and the time you have taken. Your api looks elegant and well documented. Please work on the above suggestions to make your changes more integrated with the existing api.

Here are few more additional improvement suggestion to make it more robust and extensible. This include the changes in existing code also. If you want, you may address this in a separate PR(s) as well.

Action Results & Error Handling

• ActionResult Structure:
  Consider including the action key in ActionResult for easier tracing in result lists:

class ActionResult {
  final String? actionKey;
  // ...rest
}

• Error Propagation:
  If an error occurs and shouldContinue: false, consider halting further action evaluation, or make this behavior configurable via a flag.

• Logging:
  Add optional logging hooks/callbacks for errors that occur during fact or action resolution, making debugging easier in production.

Type Safety & Null Handling

• Condition Helper Null Guards:
  All helpers (e.g., eq, neq, etc.) should explicitly handle null to avoid unexpected errors during condition evaluation.

• Helper Method Extension:
  Consider extending helpers to support deep property checks or custom comparators for complex fact structures.

Immutability Option

• Fact Immutability:
  Optionally provide a way to make facts or actions immutable after registration, to avoid accidental runtime mutation in critical systems.

Extensibility

• Plugin/Extension Mechanism:
  Consider allowing users to register middleware or hooks that can intercept fact evaluation, action selection, or results processing (e.g., for logging, audit, or A/B testing).

Testing Enhancements

• Test Coverage:

  • Add tests for concurrency, especially if facts are updated rapidly or in async environments.
  • Include negative tests (e.g., for invalid fact providers, failing actions, etc.).

Documentation & Examples

• Usage Examples:
  Enrich doc comments with more advanced usage, especially around chaining, async facts, error handling, and custom condition helpers.

Performance

• Fact Refresh Optimization:
  If dynamic fact providers are expensive, consider caching or de-duping within a single trigger cycle.

• Batch Execution:
  For many actions, consider parallelizing async action executions where order does not matter.

Resource Management

• Stream/Subscription Safety:
  If in the future, fact providers use streams or subscriptions, ensure dispose() closes them gracefully.

Edge Case Handling

• Fact/Action Key Collisions:
  Add checks or warnings for duplicate fact/action keys to avoid silent overrides.

[anidotnet]

There are tests failures. Please resolve those issues as well.

[kasutu]

Thanks for the review much appreciated!