perf: optimize rule engine with Flow-based lazy evaluation (#677)

- Replace Sequence with Flow for suspend function compatibility
- Enable early termination in aggregation modes (SINGLE, ANY, IntRuleMode)
- Add AnyKit utilities for lenient type conversion (asInt, asBoolean)
- Properly handle CancellationException for Flow exception transparency
- Add comprehensive documentation to RuleModes and AnyKit

This addresses performance issues by:
- Short-circuiting rule evaluation when terminal operators find satisfying results
- Avoiding eager collection of all rule results when only first is needed

Closes #669

Author: tangcent

src/main/kotlin/com/itangcent/easyapi/rule/RuleKey.kt

@@ -16,7 +16,7 @@ package com.itangcent.easyapi.rule
  */
 sealed class RuleKey<T>(
     val name: String,
-    val mode: RuleMode,
+    val mode: RuleMode<T>,
     val aliases: List<String> = emptyList()
 ) {
     /** All config key names (primary + aliases) that should be looked up. */
@@ -26,7 +26,7 @@ sealed class RuleKey<T>(
         name: String,
         mode: StringRuleMode = StringRuleMode.SINGLE,
         aliases: List<String> = emptyList()
-    ) : RuleKey<String?>(name, mode, aliases) {
+    ) : RuleKey<String>(name, mode, aliases) {
         val stringMode: StringRuleMode get() = mode as StringRuleMode
     }
 
@@ -41,7 +41,7 @@ sealed class RuleKey<T>(
     class IntKey(
         name: String,
         aliases: List<String> = emptyList()
-    ) : RuleKey<Int?>(name, IntRuleMode, aliases)
+    ) : RuleKey<Int>(name, IntRuleMode, aliases)
 
     class EventKey(
         name: String,
@@ -56,9 +56,12 @@ sealed class RuleKey<T>(
     companion object {
         fun string(name: String, mode: StringRuleMode = StringRuleMode.SINGLE, aliases: List<String> = emptyList()) =
             StringKey(name, mode, aliases)
+
         fun boolean(name: String, mode: BooleanRuleMode = BooleanRuleMode.ANY, aliases: List<String> = emptyList()) =
             BooleanKey(name, mode, aliases)
+
         fun int(name: String, aliases: List<String> = emptyList()) = IntKey(name, aliases)
+
         fun event(name: String, mode: EventRuleMode = EventRuleMode.IGNORE_ERROR, aliases: List<String> = emptyList()) =
             EventKey(name, mode, aliases)
     }

src/main/kotlin/com/itangcent/easyapi/rule/RuleModes.kt

@@ -1,49 +1,61 @@
 package com.itangcent.easyapi.rule
 
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.firstOrNull
+import kotlinx.coroutines.flow.toList
+import kotlinx.coroutines.flow.filter
+import kotlinx.coroutines.flow.mapNotNull
+import kotlinx.coroutines.flow.takeWhile
+
 /**
- * Base interface for rule evaluation modes.
+ * Defines how multiple rule values are aggregated into a single result.
  *
- * Determines how multiple rule values are aggregated when
- * the same rule is defined in multiple configuration files.
+ * @param T the type of values being aggregated
  */
-sealed interface RuleMode
+sealed interface RuleMode<T> {
+    /**
+     * Aggregates multiple rule results into a single value.
+     *
+     * @param values The flow of results to aggregate
+     * @return The aggregated result
+     */
+    suspend fun aggregate(values: Flow<RuleResult<T>>): T?
+}
 
 /**
  * Modes for rules that produce string values.
  *
  * Defines how multiple string values are combined.
  */
-sealed class StringRuleMode : RuleMode {
-    /**
-     * Aggregates multiple string values into a single result.
-     *
-     * @param values The list of values to aggregate
-     * @return The aggregated result
-     */
-    abstract fun aggregate(values: List<String?>): String?
+sealed class StringRuleMode : RuleMode<String> {
+    abstract override suspend fun aggregate(values: Flow<RuleResult<String>>): String?
 
     /**
      * Returns the first non-empty value.
      * Use for rules where only one value should be used.
      */
     data object SINGLE : StringRuleMode() {
-        override fun aggregate(values: List<String?>): String? = values.firstOrNull { !it.isNullOrEmpty() }
+        override suspend fun aggregate(values: Flow<RuleResult<String>>): String? =
+            values.mapNotNull { it.result }.firstOrNull { it.isNotEmpty() }
     }
 
     /**
      * Merges all non-empty values with newlines.
      * Use for rules where all values should be combined.
      */
     data object MERGE : StringRuleMode() {
-        override fun aggregate(values: List<String?>): String? = values.filterNotNull().filter { it.isNotEmpty() }.joinToString("\n").ifEmpty { null }
+        override suspend fun aggregate(values: Flow<RuleResult<String>>): String? =
+            values.mapNotNull { it.result }.filter { it.isNotEmpty() }.toList().joinToString("\n").ifEmpty { null }
     }
 
     /**
      * Merges distinct non-empty values with newlines.
      * Use for rules where duplicate values should be removed.
      */
     data object MERGE_DISTINCT : StringRuleMode() {
-        override fun aggregate(values: List<String?>): String? = values.filterNotNull().filter { it.isNotEmpty() }.distinct().joinToString("\n").ifEmpty { null }
+        override suspend fun aggregate(values: Flow<RuleResult<String>>): String? =
+            values.mapNotNull { it.result }.filter { it.isNotEmpty() }.toList().distinct().joinToString("\n")
+                .ifEmpty { null }
     }
 }
 
@@ -52,30 +64,25 @@ sealed class StringRuleMode : RuleMode {
  *
  * Defines how multiple boolean values are combined.
  */
-sealed class BooleanRuleMode : RuleMode {
-    /**
-     * Aggregates multiple boolean values into a single result.
-     *
-     * @param values The list of values to aggregate
-     * @return The aggregated result
-     */
-    abstract fun aggregate(values: List<Boolean?>): Boolean
+sealed class BooleanRuleMode : RuleMode<Boolean> {
+    abstract override suspend fun aggregate(values: Flow<RuleResult<Boolean>>): Boolean
 
     /**
      * Returns true if any value is true.
      * Use for rules like "ignore" or "required".
      */
     data object ANY : BooleanRuleMode() {
-        override fun aggregate(values: List<Boolean?>): Boolean = values.any { it == true }
+        override suspend fun aggregate(values: Flow<RuleResult<Boolean>>): Boolean =
+            values.mapNotNull { it.result }.firstOrNull { it } != null
     }
 
     /**
      * Returns true only if all non-null values are true.
      * Use for rules that require all conditions to be met.
      */
     data object ALL : BooleanRuleMode() {
-        override fun aggregate(values: List<Boolean?>): Boolean {
-            val nonNull = values.filterNotNull()
+        override suspend fun aggregate(values: Flow<RuleResult<Boolean>>): Boolean {
+            val nonNull = values.mapNotNull { it.result }.toList()
             return nonNull.isNotEmpty() && nonNull.all { it }
         }
     }
@@ -86,7 +93,10 @@ sealed class BooleanRuleMode : RuleMode {
  *
  * Event rules are executed for their side effects and don't produce values.
  */
-sealed class EventRuleMode : RuleMode {
+sealed class EventRuleMode : RuleMode<Unit> {
+
+    abstract override suspend fun aggregate(values: Flow<RuleResult<Unit>>): Unit?
+
     /**
      * Whether to throw an exception when an event handler fails.
      */
@@ -96,13 +106,29 @@ sealed class EventRuleMode : RuleMode {
      * Ignores errors and continues execution.
      */
     data object IGNORE_ERROR : EventRuleMode() {
+        override suspend fun aggregate(values: Flow<RuleResult<Unit>>): Unit? {
+            values.collect {}
+            return null
+        }
+
         override val throwOnError: Boolean = false
     }
 
     /**
      * Throws an exception on error.
      */
     data object THROW_IN_ERROR : EventRuleMode() {
+        override suspend fun aggregate(values: Flow<RuleResult<Unit>>): Unit? {
+            var error: Throwable? = null
+            values.collect { result ->
+                if (result.error != null && error == null) {
+                    error = result.error
+                }
+            }
+            error?.let { throw it }
+            return null
+        }
+
         override val throwOnError: Boolean = true
     }
 }
@@ -112,12 +138,71 @@ sealed class EventRuleMode : RuleMode {
  *
  * Returns the first non-null value.
  */
-data object IntRuleMode : RuleMode {
+data object IntRuleMode : RuleMode<Int> {
     /**
      * Returns the first non-null integer value.
      *
-     * @param values The list of values to aggregate
+     * @param values The flow of results to aggregate
      * @return The first non-null value, or null
      */
-    fun aggregate(values: List<Int?>): Int? = values.firstOrNull { it != null }
+    override suspend fun aggregate(values: Flow<RuleResult<Int>>): Int? =
+        values.mapNotNull { it.result }.firstOrNull()
+}
+
+/**
+ * Result of a rule evaluation.
+ *
+ * @param T the type of the result value
+ */
+interface RuleResult<T> {
+    /**
+     * The result value, or null if the rule didn't produce a value or failed.
+     */
+    val result: T?
+
+    /**
+     * The error that occurred during evaluation, or null if successful.
+     */
+    val error: Throwable?
+
+    companion object {
+        /**
+         * Creates a successful result with the given value.
+         */
+        fun <T> success(result: T?): RuleResult<T> =
+            if (result == null) NULL() else Success(result)
+
+        /**
+         * Creates a failure result with the given error.
+         */
+        fun <T> failure(error: Throwable): RuleResult<T> = Failure(error)
+
+        /**
+         * Creates a null result.
+         */
+        fun <T> NULL() = NullInstance as RuleResult<T>
+    }
+}
+
+/**
+ * A successful rule result.
+ */
+data class Success<T>(override val result: T) : RuleResult<T> {
+    override val error: Throwable?
+        get() = null
+}
+
+/**
+ * A failed rule result.
+ */
+data class Failure<T>(override val error: Throwable) : RuleResult<T> {
+    override val result: T? = null
+}
+
+/**
+ * A null rule result.
+ */
+object NullInstance : RuleResult<Any> {
+    override val result = null
+    override val error: Throwable? = null
 }