# Order class

Specifies the order of precedence for a class when processed by the framework or runtime system.

The `@Order` annotation provides deterministic ordering for components such as:

- Middleware
- Interceptors
- Initializers
- Filters
- Event handlers

The lower the value, the higher the priority. That is, `@Order(0)` runs before `@Order(1)`, and so on.

## 🔁 Execution Order Rules:

- Ascending Order: Lower `value` means earlier execution.
- If two components have the same `@Order`, their relative order is undefined unless explicitly handled by the framework.
- Classes without `@Order` may be given a default priority, e.g., `@Order(1000)` or treated as "last".

## 🧪 Example:

    @Order(1)
    class FirstMiddleware {}

    @Order(2)
    class SecondMiddleware {}

    @Order(0)
    class HighestPriority {}

In this example, the order of invocation would be:

1. `HighestPriority`
2. `FirstMiddleware`
3. `SecondMiddleware`

## 🧱 Common Use Cases:

Use Case | Why `@Order` Helps
--- | ---
Middleware Chains | Defines filter/interceptor execution flow
Plugin Systems | Ensures predictable hook registration
Application Phases | Orders startup or shutdown hooks
Event Listeners | Prioritizes listeners in a dispatch tree

## 🔧 Usage Notes:

- `@Order` must be placed on class declarations only.
- Typically interpreted by the container, registry, or dispatcher at runtime or compile-time.
- It is framework-agnostic, but effective only if the underlying system respects the ordering logic.

## 🎯 Target:

This annotation applies to classes only:

    @Order(10)
    class AuditLoggerInterceptor {}

## 🧩 Related Patterns:

- Chain of Responsibility
- Interceptor / Middleware
- Application lifecycle hooks (e.g., startup, shutdown)

## 🔄 Integration Tip:

Frameworks can use this annotation to sort registered components:

    final List<Object> ordered = components
        .whereType<HasOrder>()
        .toList()
      ..sort((a, b) => a.order.compareTo(b.order));

Consider defining a common interface like `HasOrder` to extract the `value`:

    abstract class HasOrder {
      int get order;
    }

## ✅ Best Practices:

- Use low values (`0–10`) for essential/core logic.
- Use mid-range values (`50–100`) for application-level logic.
- Avoid overusing `@Order` — prefer natural dependency ordering when possible.
- Combine with composition or configuration patterns for more flexibility.

Inheritance
  - Object
  - ReflectableAnnotation
  - Order
Mixed-in types
  - EqualsAndHashCode
Annotations
  - @Target({TargetKind.classType})

## Constructors

Order.new(int value)
  Specifies the order of precedence for a class when processed by the framework or runtime system.
  const

## Properties

annotationType → Type
  Returns the annotation _type of this annotation.
  no setter override
hashCode → int
  The hash code for this object.
  no setter inherited
runtimeType → Type
  A representation of the runtime type of the object.
  no setter inherited
value → int
  The precedence value. Classes with lower values are executed first.
  final

## Methods

equalizedProperties() → List<Object?>
  Mixin-style contract for value-based equality, `hashCode`, and `toString`.
  override
equals(Object other) → bool
  Checks whether the given object is logically equivalent to this annotation.
  inherited
noSuchMethod(Invocation invocation) → dynamic
  Invoked when a nonexistent method or property is accessed.
  inherited
toString() → String
  A string representation of this object.
  inherited

## Operators

operator ==(Object other) → bool
  The equality operator.
  inherited