String Validator Plugin

The String Validator plugin for Flatfile provides a comprehensive way to validate and transform string data during the import process. It allows you to configure multiple validation rules for specified fields in a single, easy-to-use configuration object.

Its main purpose is to enforce data quality and consistency for string-based fields. Key features include validating strings against regular expression patterns (both common predefined patterns like email and URL, and custom ones), enforcing length constraints (min, max, or exact), and ensuring proper casing (lowercase, uppercase, or titlecase). The plugin can also automatically trim leading or trailing whitespace.

Use cases include cleaning user-submitted data, ensuring identifiers match a specific format (e.g., ‘ABC-123’), validating contact information like emails and phone numbers, and standardizing the case of names or categories before they are imported into a system. If a value doesn’t meet a validation rule but can be corrected (e.g., wrong case, extra whitespace), the plugin will automatically transform the value and notify the user of the change.

​

Installation

Install the plugin using npm:

npm install @flatfile/plugin-validate-string

​

Configuration & Parameters

The plugin is configured with a single StringValidationConfig object with the following properties:

​

Required Parameters

​

Optional Parameters

​

Usage Examples

​

Basic Usage

import { FlatfileListener } from '@flatfile/listener';
import { validateString } from '@flatfile/plugin-validate-string';

const listener = new FlatfileListener();

listener.use(validateString({
  fields: ['firstName', 'lastName'],
  minLength: 2,
  maxLength: 50,
  caseType: 'titlecase'
}));

​

Email Validation

import { FlatfileListener } from '@flatfile/listener';
import { validateString } from '@flatfile/plugin-validate-string';

const listener = new FlatfileListener();

listener.use(validateString({
  fields: ['email'],
  pattern: 'email',
  emptyStringAllowed: false,
  errorMessages: {
    pattern: 'Please provide a valid email address.',
    length: 'The email address is too long.'
  }
}));

​

Advanced Custom Pattern Validation

import { FlatfileListener } from '@flatfile/listener';
import { validateString } from '@flatfile/plugin-validate-string';

const listener = new FlatfileListener();

// Example: Validate a product SKU that must be in the format 'SKU-12345'
listener.use(validateString({
  fields: ['product_sku'],
  pattern: /^SKU-\d{5}$/,
  caseType: 'uppercase',
  errorMessages: {
    pattern: 'SKU must be in the format SKU-XXXXX, where X is a digit.',
    case: 'SKU must be in uppercase.'
  }
}));

​

Using the Utility Function

import { validateAndTransformString } from '@flatfile/plugin-validate-string';

const config = {
  fields: ['email'],
  pattern: 'email'
};

const result1 = validateAndTransformString('test@example.com', config);
// result1 -> { value: 'test@example.com', error: null }

const result2 = validateAndTransformString('not-an-email', config);
// result2 -> { value: 'not-an-email', error: 'Invalid format' }

​

Error Handling Example

import { validateAndTransformString } from '@flatfile/plugin-validate-string';

const config = {
  fields: ['code'],
  exactLength: 5
};

const result = validateAndTransformString('ABC', config);
if (result.error) {
  console.log(`Validation failed: ${result.error}`);
  // Logs: "Validation failed: Exact length must be 5"
}

​

API Reference

​

validateString(config)

The main entry point for the plugin. It configures and registers a recordHook that listens for new commits and applies the specified string validations to each record.

Parameters:

• config (StringValidationConfig): An object that defines the validation and transformation rules.

Returns: A function that takes a FlatfileListener instance and attaches the validation logic to it.

​

validateAndTransformString(value, config)

An exported utility function that runs the validation and transformation logic on a single string value. It is used internally by the plugin but can be used for custom validation logic if needed.

Parameters:

• value (string): The input string to validate and transform.
• config (StringValidationConfig): The configuration object defining the rules to apply.

Returns: An object of type ValidationResult with two properties:

• value (string): The original or transformed string value.
• error (string | null): An error message string if any validation fails, otherwise null.

​

Notes

​

Default Behavior

• Empty strings: By default, empty strings are considered invalid. To allow them, you must explicitly set emptyStringAllowed: true in the configuration.
• Sheet targeting: When no sheetSlug is specified, the plugin applies to all sheets in the workbook using the default value ’**’.
• Error messages: The plugin provides default error messages for each validation type (e.g., “Invalid format”, “Minimum length is X”) which can be customized using the errorMessages configuration option.

​

Important Considerations

• The plugin operates using the @flatfile/plugin-record-hook, which is a dependency. It processes records individually during the commit:created event.
• The plugin can modify data. When a transformation is applied (e.g., changing case or trimming whitespace), the record’s value is updated with record.set().
• By default, when a transformation is applied, the plugin also adds a validation message to the cell (e.g., “Field value must be in titlecase”). This informs the user that their original data was automatically corrected.
• The plugin handles null and undefined values by simply skipping them. Validation is only applied to defined string values.
• The plugin does not throw exceptions. Instead, it captures validation failures and adds them as errors to the corresponding record and field using record.addError(field, message). These errors are then visible to the user in the Flatfile UI.