ValueRange class

ValueRange is a specialized TestRule metadata annotation designed to validate whether a numeric input falls within a specific inclusive boundary.

It provides a declarative mechanism for Numeric Domain Constraint, allowing the cell.core framework and auxiliary tools (like build_model) to enforce business invariants directly at the field level.

When to use

Use this on numeric fields (e.g., int, double) to restrict their values to a specific inclusive range. Common examples: age (1-120), percentage (0.0-1.0), temperature, coordinates.

How it works

The generated validation code checks that the value is within min and max inclusive. Non‑numeric values (like null or strings) pass validation to allow flexible annotation usage on optional fields.

Non‑obvious

  • The range is inclusive: min <= value <= max.
  • null and non‑numeric values are allowed (return true). This is intentional – use @DefaultValue to provide a default if needed.
  • If the field is nullable and you want to disallow null, you can combine with a separate TestRule or handle it in code.

Examples

1. Percentage / Ratio Constraints

@ValueRange(min: 0.0, max: 1.0)
final double opacity;

2. Physical / Logical Limits

@ValueRange(min: 1, max: 120)
final int age; // Human age logic constraint

@ValueRange(min: -180, max: 180)
final double longitude;

Parameters

  • min: The inclusive lower bound. Any value < min will fail validation.
  • max: The inclusive upper bound. Any value > max will fail validation.

Validation Logic:

  • If the object is a num, it checks min <= value <= max.
  • Non-numeric objects are considered "Pass" (true) by default, allowing the annotation to be used flexibly on optional or dynamic fields.
Inheritance

Constructors

ValueRange({required num min, required num max})
Creates a new ValueRange rule for numeric range validation.
const

Properties

hashCode → int
The hash code for this object.
no setterinherited
max → num
The inclusive upper bound of the valid range.
final
min → num
The inclusive lower bound of the valid range.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

call(dynamic object, {covariant Never host, dynamic arguments}) → FutureOr<bool>
Executes validation by checking if object is a num within min..max.
override
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 +(covariant TestRule<Never> other) → TestRule<Never>
Composes two TestRule instances into a sequential Validation Pipeline.
inherited
operator ==(Object other) → bool
The equality operator.
inherited