ExecutableSelector class abstract interface

A flexible executable filtering and selection utility used to pick a single Executable (e.g., a constructor, method, or function overload) from a provided list based on declarative matching rules.

ExecutableSelector supports two categories of selection criteria:

1. Type-Based Matching

Using and, you can require that at least one parameter of the executable matches a given Class type.

Matching behavior depends on isAssignableFrom:

• If true (default):
  The executable’s parameter type may be a subtype of the given type.
  Example: selecting constructors accepting ApplicationContext when registering ContextAware.

• If false:
  The executable’s parameter type must be a supertype or exact match. Useful when selecting overloads with more specific parameter constraints.

2. Predicate-Based Matching

Using when, callers can register arbitrary custom filters that operate on individual parameters.

These allow highly granular control such as:

• selecting executables with parameters named "config"
• matching only positional parameters
• detecting the presence of certain annotations
• checking for nullability, generic types, or metadata flags

Predicates are evaluated against all parameters of each executable.
If any parameter satisfies the predicate, the executable qualifies for that rule.

🔍 Selection Process

When select is invoked:

1. All registered type-based and predicate-based rules are applied to each executable in the provided list.
2. An executable must satisfy all rules to be considered a match.
3. If multiple matches exist, the internal implementation may apply prioritization (e.g., first declared, most specific, etc.).
4. The selected executable is returned; if none match, an error may be thrown or null returned depending on the implementation.

🧪 Example

final selector = ExecutableSelector()
  .and(Class<ApplicationContext>())
  .when((param) => param.isNamed && param.name == 'logger');

final executable = selector.select(myClass.getConstructors());

This example selects a constructor or method that:

• has a parameter assignable from ApplicationContext
• AND has a named parameter called "logger"

🧩 Use Cases

• Choosing the “best” constructor when instantiating classes via reflection
• Selecting method overloads based on runtime type information
• Filtering plugin entry points or lifecycle methods
• Creating extensible and declarative DI-friendly selection logic

⚠️ Notes

• Selection rules are additive; an executable must satisfy every rule.
• Ordering of rules does not affect correctness but may influence optimization in internal implementations.
• If the list contains only one executable, selection may short-circuit.