Special Cases

Nullable parameters

When a SimpleEntity contains a nullable modddel, when it is null, it is considered valid during the contentValidationStep.

If you want a nullable modddel to cause a failure when it's null, you should use the @NullFailure annotation.

The @validParam Annotation

Sometimes, you want a SimpleEntity to contain a ValidModddel (1), or a parameter that isn't a modddel and that should be considered as being valid (2). In these cases, you can annotate it with @validParam.

Example :

factory Person({
    required FullName name,
    /// (1)
    @validParam required ValidAge age,
    /// (2) More frequent usecase
    @validParam required bool isMarried,
  }) { ...

In this example, the contentValidation will be skipped for both age and isMarried.

The parameters of a SimpleEntity can't all be annotated with @validParam. If you feel the need to do so, and either :

  • Your entity only has one validation which is the contentValidation : This would mean that the entity would always be valid, which is not allowed. For an alternative, see this section.

  • Your entity has multiple validations : Use a MultiValueObject instead.

The @invalidParam Annotation

Sometimes (rarely), you want a SimpleEntity to contain an InvalidModddel. In that case, you can annotate it with @invalidParam.

Example :

factory FreeArticle({
    required Description description,
    @invalidParam required InvalidPrice? price,
  }) { ...

In this example, InvalidPrice is the invalid union-case of a Price modddel. If price is null, then it's considered valid during the contentValidation. However, if it's not null, then the contentValidation fails with its failures.

If FreeArticle passes the contentValidationStep, it means that price is null. As a result, the union-cases that come after the contentValidationStep will hold the null version of price : Null price. We call this the Null param transformation.

The parameter annotated with @invalidParam must be nullable. That's because, if if is non-nullable, the SimpleEntity would always be invalid, while fundamentally a Modddel can either be valid or invalid.

For an alternative, see this section.