Breaking change: rename scalePrecision to precisionScale and interpret terms correctly

Author: AlexJPotter

.idea/runConfigurations/All_Tests.xml

@@ -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
+
+In releases 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

docs/api/rules/precisionScale.md

@@ -0,0 +1,31 @@
+import { Rule } from './Rule';
+
+export class PrecisionScaleRule<TModel, TValue> extends Rule<TModel, TValue> {
+  constructor(precision: number, scale: number) {
+    // istanbul ignore next - https://github.com/gotwarlost/istanbul/issues/690
+    super((value: TValue) => {
+      if (value == null || value === 0) {
+        return null;
+      }
+      if (typeof value !== 'number') {
+        throw new TypeError('A non-number value was passed to the precisionScale rule');
+      }
+
+      const regex = precisionScaleRegex({ precision, scale });
+
+      if (!regex.test(value.toString())) {
+        return `Value must not be more than ${precision} digits in total, with allowance for ${scale} decimals`;
+      }
+
+      return null;
+    });
+  }
+}
+
+const precisionScaleRegex = ({ precision, scale }: { precision: number; scale: number }) => {
+  const integerDigits = precision - scale;
+
+  return integerDigits === 0
+    ? new RegExp(`^-?0?\\.\\d{0,${scale}}$`) // The leading 0 to the left of the decimal point does not count towards precision
+    : new RegExp(`^-?\\d{1,${integerDigits}}(\\.\\d{1,${scale}})?$`);
+};

docs/api/rules/scalePrecision.md

@@ -56,7 +56,7 @@ export type AsyncRuleValidators<TModel, TValue> = {
     TValue,
     (lowerBound: number, upperBound: number) => AsyncRuleValidatorsAndExtensions<TModel, TValue>
   >;
-  scalePrecision: IfNumber<
+  precisionScale: IfNumber<
     TValue,
     (precision: number, scale: number) => AsyncRuleValidatorsAndExtensions<TModel, TValue>
   >;

src/rules/PrecisionScaleRule.ts

@@ -19,7 +19,7 @@ import { NotEqualRule } from '@/rules/NotEqualRule';
 import { NotNullRule, NotNullRuleOptions } from '@/rules/NotNullRule';
 import { NullRule, NullRuleOptions } from '@/rules/NullRule';
 import { Rule } from '@/rules/Rule';
-import { ScalePrecisionRule } from '@/rules/ScalePrecisionRule';
+import { PrecisionScaleRule } from '@/rules/PrecisionScaleRule';
 import { ValidatorRule } from '@/rules/ValidatorRule';
 import { Predicate } from '@/types/Predicate';
 import { AppliesTo } from '@/types/AppliesTo';
@@ -240,12 +240,12 @@ export abstract class CoreValueValidatorBuilder<
     return this.getAllRulesAndExtensions();
   };
 
-  public scalePrecision = (precision: number, scale: number) => {
-    if (scale - precision <= 0) {
-      throw new Error('Invalid scale and precision were passed to the scalePrecision rule');
+  public precisionScale = (precision: number, scale: number) => {
+    if (precision < 1 || scale < 0 || precision < scale) {
+      throw new Error('Invalid scale and precision were passed to the precisionScale rule');
     }
-    const scalePrecisionRule = new ScalePrecisionRule<TModel, TTransformedValue>(precision, scale);
-    this.pushRule(scalePrecisionRule);
+    const precisionScaleRule = new PrecisionScaleRule<TModel, TTransformedValue>(precision, scale);
+    this.pushRule(precisionScaleRule);
     return this.getAllRulesAndExtensions();
   };
 
@@ -270,7 +270,7 @@ export abstract class CoreValueValidatorBuilder<
     exclusiveBetween: this.exclusiveBetween,
     inclusiveBetween: this.inclusiveBetween,
     setValidator: this.setValidator,
-    scalePrecision: this.scalePrecision,
+    precisionScale: this.precisionScale,
   });
 
   protected abstract getAllRules: () => TRuleValidators;

src/rules/ScalePrecisionRule.ts

@@ -40,7 +40,7 @@ export type RuleValidators<TModel, TValue> = {
     TValue,
     (lowerBound: number, upperBound: number) => RuleValidatorsAndExtensions<TModel, TValue>
   >;
-  scalePrecision: IfNumber<
+  precisionScale: IfNumber<
     TValue,
     (precision: number, scale: number) => RuleValidatorsAndExtensions<TModel, TValue>
   >;