> ## Documentation Index
> Fetch the complete documentation index at: https://flatfile.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# String Validator Plugin
> A comprehensive plugin for validating and transforming string data during the Flatfile import process with configurable validation rules, pattern matching, and automatic data corrections.
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:
```bash theme={null}
npm install @flatfile/plugin-validate-string
```
## Configuration & Parameters
The plugin is configured with a single `StringValidationConfig` object with the following properties:
### Required Parameters
An array of field keys (column names) to which the validation rules should be applied.
### Optional Parameters
The slug of a specific sheet to apply the validations to. Defaults to '\*\*' (applies to all sheets in the workbook).
A regular expression to validate the string against. You can use one of the predefined string keys for common patterns ('email', 'phone', 'url') or provide your own custom RegExp object.
The minimum allowed length for the string.
The maximum allowed length for the string.
The exact required length for the string.
Enforces a specific character case. If the input string does not match, it will be transformed, and a validation message will be added.
An object to control whitespace trimming. If `leading` is true, it trims whitespace from the start. If `trailing` is true, it trims from the end. If the string is trimmed, the value is transformed, and a message is added.
Controls whether an empty string is considered a valid value. By default, empty strings will generate a "Field cannot be empty" error.
An object to provide custom error messages for different validation types, overriding the default messages. The plugin provides default messages for each validation type (e.g., "Invalid format", "Minimum length is X").
## Usage Examples
### Basic Usage
```javascript JavaScript theme={null}
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'
}));
```
```typescript TypeScript theme={null}
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
```javascript JavaScript theme={null}
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.'
}
}));
```
```typescript TypeScript theme={null}
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
```javascript JavaScript theme={null}
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.'
}
}));
```
```typescript TypeScript theme={null}
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
```javascript JavaScript theme={null}
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' }
```
```typescript TypeScript theme={null}
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
```javascript JavaScript theme={null}
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"
}
```
```typescript TypeScript theme={null}
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.