Number Validation Plugin
Comprehensive validation for numeric data during the Flatfile import process with support for ranges, formats, and special number types.
The Number Validation Plugin for Flatfile provides comprehensive validation for numeric data during the import process. It attaches to the commit:created
listener event to analyze and validate data from specified fields.
Its main purpose is to ensure that numeric data conforms to a wide range of rules before being accepted into the system. Use cases include:
- Enforcing value ranges (e.g., age must be between 18 and 65)
- Validating data formats like integers, currency, or numbers with specific precision and scale
- Ensuring numbers follow specific rules, such as being a multiple of a certain value (step validation)
- Checking for special numeric properties like being even, odd, or prime
- Automatically cleaning up number formats by handling thousands separators and decimal points
- Optionally rounding or truncating numbers before validation
The plugin modifies records by setting the cleaned, parsed numeric value and attaching any validation errors or warnings directly to the relevant field.
Installation
Install the plugin using npm:
Configuration & Parameters
The validateNumber
function accepts a single configuration object with the following properties:
Required Parameters
Parameter | Type | Description |
---|---|---|
fields | string[] | An array of field keys (column names) to which the validation rules should be applied |
Optional Parameters
Parameter | Type | Default | Description |
---|---|---|---|
sheetSlug | string | '**' | The slug of the sheet to apply the validation to. Defaults to all sheets |
min | number | undefined | The minimum allowed value for the number |
max | number | undefined | The maximum allowed value for the number |
inclusive | boolean | false | Determines if the min and max values are inclusive |
integerOnly | boolean | false | If true, the value must be an integer (no decimal part) |
precision | number | undefined | The total maximum number of digits allowed (requires scale to be set) |
scale | number | undefined | The maximum number of digits allowed after the decimal point (requires precision to be set) |
currency | boolean | false | If true, validates that the number is a valid currency format, allowing up to two decimal places |
step | number | undefined | The value must be a multiple of this number |
thousandsSeparator | string | ',' | The character used as a thousands separator in the input string |
decimalPoint | string | '.' | The character used as the decimal point in the input string |
specialTypes | string[] | undefined | An array of special number types to validate against. Supported values: 'prime' , 'even' , 'odd' |
round | boolean | false | If true, the number is rounded to the nearest integer before validation |
truncate | boolean | false | If true, the decimal part of the number is removed before validation |
Usage Examples
Basic Usage
Currency Validation
Direct Validation Function
API Reference
validateNumber
The main plugin entry point that returns a function for use with listener.use()
.
Parameters:
config
(object): Configuration object containing validation rules and target fields
Returns:
A function of type (listener: FlatfileListener) => void
that registers the validation hook.
Example:
validateNumberField
A standalone utility function that validates a single value against validation rules.
Parameters:
value
(string | number): The input value to validateconfig
(NumberValidationConfig): Configuration object with validation rules
Returns:
NumberValidationResult
object with:
value
(number | null): The parsed numeric value or null if parsing failederrors
(string[]): Array of error messages for fundamental parsing failureswarnings
(string[]): Array of warning messages for validation rule violations
Error Handling Example:
isPrime
A helper function to check if a number is prime. Used internally when specialTypes: ['prime']
is configured.
Parameters:
num
(number): The number to check
Returns:
boolean
- True if the number is prime, false otherwise
Troubleshooting
- Validation not working: Check the
fields
andsheetSlug
configuration to ensure the plugin is targeting the correct data - Unexpected number formats: Verify the
thousandsSeparator
anddecimalPoint
settings match your data format - Reference examples: The test file
src/validate.number.plugin.spec.ts
provides clear examples of expected outcomes for every configuration option
Notes
Default Behavior
- The
min
/max
validation is exclusive by default. To include boundary values, setinclusive: true
- Default
thousandsSeparator
is','
anddecimalPoint
is'.'
- If both
round
andtruncate
are true, rounding occurs first, then truncation
Special Considerations
- The plugin operates on the
commit:created
event, running after user submission but before data finalization - The plugin modifies
FlatfileRecord
in place, overwriting original values with parsed numeric values - Fundamental parsing failures (e.g., “abc” as a number) result in “errors”
- Rule violations (e.g., number outside min/max range) result in “warnings”
- The plugin follows standard Flatfile patterns by adding errors/warnings to records rather than throwing exceptions