Version 5.0.0 - breaking changes: when and unless conditions only apply to rules defined since last when/unless call, rename scalePrecision to precisionScale and interpret terms correctly

Author: AlexJPotter

.idea/runConfigurations/All_Tests.xml

@@ -7,6 +7,12 @@ The `.unless` option is used to control when a rule or chain of rules should **n
 
 By default, the `.unless` option will apply to all rules in the chain so far, but you can pass a second parameter to specify that it should only apply to the rule immediately preceding it.
 
+:::note
+
+In the case that there are multiple `.when` and/or `.unless` conditions in the rule chain, each condition applies only to the rules defined **between it and the previous condition**.
+
+:::
+
 ## Examples
 
 ### Apply to all rules in the chain so far
@@ -51,6 +57,59 @@ formValidator.validate({
 // ❌ { deliveryNote: 'Value cannot be null' }
 ```
 
+### Multiple calls within the same chain
+
+In this example we apply multiple `.unless` conditions within the same rule chain.
+
+In particular, we validate that the account balance is non-negative unless overdrafts are allowed, and also validate that the account balance is more than 100 unless the account is not subject to minimum balance requirements.
+
+```typescript
+import { Validator } from 'fluentvalidation-ts';
+
+type FormModel = {
+  accountBalance: number;
+  allowOverdrafts: boolean;
+  subjectToMinimumBalance: boolean;
+};
+
+class FormValidator extends Validator<FormModel> {
+  constructor() {
+    super();
+
+    this.ruleFor('accountBalance')
+      .greaterThanOrEqualTo(0)
+      // highlight-next-line
+      .unless((formModel) => formModel.allowOverdrafts)
+      .greaterThanOrEqualTo(100)
+      // highlight-next-line
+      .unless((formModel) => !formModel.subjectToMinimumBalance);
+  }
+}
+
+const formValidator = new FormValidator();
+
+formValidator.validate({
+  accountBalance: -50,
+  allowOverdrafts: true,
+  subjectToMinimumBalance: false,
+});
+// ✔ {}
+
+formValidator.validate({
+  accountBalance: -50,
+  allowOverdrafts: false,
+  subjectToMinimumBalance: false,
+});
+// ❌ { accountBalance: 'Value must be greater than or equal to 0' }
+
+formValidator.validate({
+  accountBalance: 50,
+  allowOverdrafts: false,
+  subjectToMinimumBalance: true,
+});
+// ❌ { accountBalance: 'Value must be greater than or equal to 100' }
+```
+
 ### Apply to a specific rule in the chain
 
 In this example we apply an `.unless` condition to a specific rule in the chain.
@@ -73,10 +132,7 @@ class FormValidator extends Validator<FormModel> {
       .notNull()
       .greaterThanOrEqualTo(18)
       // highlight-start
-      .unless(
-        (formModel) => formModel.alcoholicDrink == null,
-        'AppliesToCurrentValidator'
-      );
+      .unless((formModel) => formModel.alcoholicDrink == null, 'AppliesToCurrentValidator');
     // highlight-end
   }
 }
@@ -122,8 +178,10 @@ Matches the type of the base model.
 
 ### `appliesTo`
 
-This is an optional parameter which can be used to control whether the condition applies to all rules in the chain so far, or just the rule immediately preceding the call to `.unless`.
+This is an optional parameter which can be used to control which rules in the current rule chain the condition applies to.
+
+A value of `'AppliesToAllValidators'` means that the `.unless` condition applies to all rules in the current rule chain so far. If there are other calls to `.when` or `.unless` in the chain, only the rules defined since the most recent condition will have the condition applied to them.
 
-By default, this parameter is set to `'AppliesToAllValidators'`, which means that the `.unless` condition applies to all rules in the current chain.
+A value of `'AppliesToCurrentValidator'` specifies that the `.unless` condition only controls the execution of the rule immediately preceding it in the current rule chain.
 
-Setting this value to `'AppliesToCurrentValidator'` specifies that the `.unless` condition only controls the execution of the rule immediately preceding it in the current chain.
+By default, the `appliesTo` parameter is set to `'AppliesToAllValidators'`.

docs/api/configuration/unless.md

@@ -7,6 +7,12 @@ The `.when` option is used to control when a rule or chain of rules should execu
 
 By default, the `.when` option will apply to all rules in the chain so far, but you can pass a second parameter to specify that it should only apply to the rule immediately preceding it.
 
+:::note
+
+In the case that there are multiple `.when` and/or `.unless` conditions in the rule chain, each condition applies only to the rules defined **between it and the previous condition**.
+
+:::
+
 ## Examples
 
 ### Apply to all rules in the chain so far
@@ -51,6 +57,51 @@ formValidator.validate({
 // ❌ { deliveryNote: 'Value cannot be null' }
 ```
 
+### Multiple calls within the same chain
+
+In this example we apply multiple `.when` conditions within the same rule chain.
+
+In particular, we validate that Sunday delivery rates are only applied when the delivery day is a Sunday.
+
+```typescript
+import { Validator } from 'fluentvalidation-ts';
+
+type FormModel = {
+  deliveryDay: string;
+  deliveryRate: number;
+};
+
+class FormValidator extends Validator<FormModel> {
+  constructor() {
+    super();
+
+    this.ruleFor('deliveryRate')
+      .equal(4.99)
+      .withMessage('Sunday rates must apply if delivery day is Sunday')
+      // highlight-next-line
+      .when((formModel) => formModel.deliveryDay === 'Sunday')
+      .equal(2.99)
+      .withMessage('Standard rates must apply if delivery day is Monday to Saturday')
+      // highlight-next-line
+      .when((formModel) => formModel.deliveryDay !== 'Sunday');
+  }
+}
+
+const formValidator = new FormValidator();
+
+formValidator.validate({ deliveryDay: 'Sunday', deliveryRate: 4.99 });
+// ✔ {}
+
+formValidator.validate({ deliveryDay: 'Sunday', deliveryRate: 2.99 });
+// ❌ { deliveryRate: 'Sunday rates must apply if delivery day is Sunday' }
+
+formValidator.validate({ deliveryDay: 'Monday', deliveryRate: 2.99 });
+// ✔ {}
+
+formValidator.validate({ deliveryDay: 'Monday', deliveryRate: 4.99 });
+// ❌ { deliveryRate: 'Standard rates must apply if delivery day is Monday to Saturday' }
+```
+
 ### Apply to a specific rule in the chain
 
 In this example we apply a `.when` condition to a specific rule in the chain.
@@ -73,10 +124,7 @@ class FormValidator extends Validator<FormModel> {
       .notNull()
       .greaterThanOrEqualTo(18)
       // highlight-start
-      .when(
-        (formModel) => formModel.alcoholicDrink != null,
-        'AppliesToCurrentValidator'
-      );
+      .when((formModel) => formModel.alcoholicDrink != null, 'AppliesToCurrentValidator');
     // highlight-end
   }
 }
@@ -122,8 +170,10 @@ Matches the type of the base model.
 
 ### `appliesTo`
 
-This is an optional parameter which can be used to control whether the condition applies to all rules in the chain so far, or just the rule immediately preceding the call to `.when`.
+This is an optional parameter which can be used to control which rules in the current rule chain the condition applies to.
+
+A value of `'AppliesToAllValidators'` means that the `.when` condition applies to all rules in the current rule chain so far. If there are other calls to `.when` or `.unless` in the chain, only the rules defined since the most recent condition will have the condition applied to them.
 
-By default, this parameter is set to `'AppliesToAllValidators'`, which means that the `.when` condition applies to all rules in the current chain.
+A value of `'AppliesToCurrentValidator'` specifies that the `.when` condition only controls the execution of the rule immediately preceding it in the current rule chain.
 
-Setting this value to `'AppliesToCurrentValidator'` specifies that the `.when` condition only controls the execution of the rule immediately preceding it in the current chain.
+By default, the `appliesTo` parameter is set to `'AppliesToAllValidators'`.

docs/api/configuration/when.md

@@ -0,0 +1,78 @@
+---
+id: precisionScale
+title: '.precisionScale'
+---
+
+The `.precisionScale` rule is used to ensure that the value of a given `number` property is permissible for the specified **precision** and **scale**.
+
+These terms are defined as follows:
+
+- **Precision** is the number of digits in a number.
+- **Scale** is the number of digits to the right of the decimal point in a number.
+
+:::warning
+
+Prior to `v5.0.0` the `.precisionScale` rule was called `.scalePrecision` and the parameter naming was incorrect!
+
+:::
+
+## Example
+
+```typescript
+import { Validator } from 'fluentvalidation-ts';
+
+type FormModel = {
+  price: number;
+};
+
+class FormValidator extends Validator<FormModel> {
+  constructor() {
+    super();
+
+    this.ruleFor('price').precisionScale(4, 2);
+  }
+}
+
+const formValidator = new FormValidator();
+
+formValidator.validate({ price: 10.01 });
+// ✔ {}
+
+formValidator.validate({ price: 0.001 }); // Too many digits after the decimal point
+// ❌ { price: 'Value must be no more than 4 digits in total, with allowance for 2 decimals' }
+
+formValidator.validate({ price: 100.1 }); // Too many digits (when accounting for reserved digits after the decimal point)
+// ❌ { price: 'Value must be no more than 4 digits in total, with allowance for 2 decimals' }
+```
+
+## Reference
+
+### `.precisionScale(precision: number, scale: number)`
+
+A number validation rule which takes in an allowed precision and scale, and ensures that the value of the given property is permissible.
+
+:::danger
+
+Due to rounding issues with floating point numbers in JavaScript, this rule may not function as expected for large precisions/scales.
+
+:::
+
+### `precision`
+
+This is the total number of digits that the value may have (taking into account the number of digits "reserved" for after the decimal point).
+
+The maximum number of significant digits allowed before the decimal point (i.e. the integer part) can be calculated as `(precision - scale)`.
+
+### `scale`
+
+This is the maximum number of digits after the decimal point that the value may have.
+
+:::note
+
+When `precision` and `scale` are equal, the "leading zero" to the left of the decimal point is **not** counted as a digit (e.g. a value of `0.01` would be viewed as `.01`).
+
+:::
+
+## Example Message
+
+> Value must not be more than `[precision]` digits in total, with allowance for `[scale]` decimals