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:

npm install @flatfile/plugin-validate-number

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

JavaScript

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

const listener = new FlatfileListener();

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

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

JavaScript

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: '.',
  })
);

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

JavaScript

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
  }
};

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

const customValidation = (): void => {
  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:

JavaScript

listener.use(
  validateNumber({
    fields: ['score'],
    min: 0,
    max: 100,
    inclusive: true,
  })
);

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:

JavaScript

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

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