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: 
npm install @flatfile/plugin-validate-number

​
Configuration & Parameters

The validateNumber function accepts a single configuration object with the following properties:

​
Required Parameters

ParameterTypeDescription
fieldsstring[]An array of field keys (column names) to which the validation rules should be applied

​
Optional Parameters

ParameterTypeDefaultDescription
sheetSlugstring'**'The slug of the sheet to apply the validation to. Defaults to all sheets
minnumberundefinedThe minimum allowed value for the number
maxnumberundefinedThe maximum allowed value for the number
inclusivebooleanfalseDetermines if the min and max values are inclusive
integerOnlybooleanfalseIf true, the value must be an integer (no decimal part)
precisionnumberundefinedThe total maximum number of digits allowed (requires scale to be set)
scalenumberundefinedThe maximum number of digits allowed after the decimal point (requires precision to be set)
currencybooleanfalseIf true, validates that the number is a valid currency format, allowing up to two decimal places
stepnumberundefinedThe value must be a multiple of this number
thousandsSeparatorstring','The character used as a thousands separator in the input string
decimalPointstring'.'The character used as the decimal point in the input string
specialTypesstring[]undefinedAn array of special number types to validate against. Supported values: 'prime', 'even', 'odd'
roundbooleanfalseIf true, the number is rounded to the nearest integer before validation
truncatebooleanfalseIf true, the decimal part of the number is removed before validation

​
Usage Examples

​
Basic Usage

import { FlatfileListener } from '@flatfile/listener';
import { validateNumber } from '@flatfile/plugin-validate-number';

const listener = new FlatfileListener();

listener.use(
  validateNumber({
    fields: ['quantity'],
    integerOnly: true,
  })
);

​
Currency Validation

import { FlatfileListener } from '@flatfile/listener';
import { validateNumber } from '@flatfile/plugin-validate-number';

const listener = new FlatfileListener();

listener.use(
  validateNumber({
    sheetSlug: 'products',
    fields: ['price'],
    min: 0,
    max: 1000000,
    inclusive: true,
    currency: true,
    precision: 9, // 7 digits before decimal, 2 after
    scale: 2,
    thousandsSeparator: ',',
    decimalPoint: '.',
  })
);

​
Direct Validation Function

import { validateNumberField } from '@flatfile/plugin-validate-number';

const customValidation = () => {
  const inputValue = '1,234.56';
  const config = { thousandsSeparator: ',', decimalPoint: '.' };

  const result = validateNumberField(inputValue, config);

  if (result.errors.length > 0) {
    console.error('Validation Errors:', result.errors);
  } else if (result.warnings.length > 0) {
    console.warn('Validation Warnings:', result.warnings);
  } else {
    console.log('Validated Value:', result.value); // Outputs: 1234.56
  }
};

​
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: 
listener.use(
  validateNumber({
    fields: ['score'],
    min: 0,
    max: 100,
    inclusive: true,
  })
);

​
validateNumberField

A standalone utility function that validates a single value against validation rules. Parameters:
  • value (string | number): The input value to validate
  • config (NumberValidationConfig): Configuration object with validation rules
Returns: NumberValidationResult object with:
  • value (number | null): The parsed numeric value or null if parsing failed
  • errors (string[]): Array of error messages for fundamental parsing failures
  • warnings (string[]): Array of warning messages for validation rule violations
Error Handling Example: 
import { validateNumberField } from '@flatfile/plugin-validate-number';

const result = validateNumberField('not-a-number', {});
console.log(result.errors); // Outputs: ['Must be a number']
console.log(result.value); // Outputs: null

const result2 = validateNumberField('99.99', { integerOnly: true });
console.log(result2.warnings); // Outputs: ['Must be an integer']
console.log(result2.value); // Outputs: 99.99

​
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 and sheetSlug configuration to ensure the plugin is targeting the correct data
  • Unexpected number formats: Verify the thousandsSeparator and decimalPoint 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, set inclusive: true
  • Default thousandsSeparator is ',' and decimalPoint is '.'
  • If both round and truncate 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