Number Validation Plugin

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

​

Optional Parameters

​

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