Constraints Plugin
Extend Flatfile validation capabilities with custom validation logic for complex field and sheet-level constraints
The Constraints plugin extends Flatfile’s validation capabilities by allowing developers to define custom validation logic, called “external constraints,” within a listener. These custom rules can then be applied to specific fields or to the entire sheet through the blueprint configuration.
The main purpose is to handle complex validation scenarios that are not covered by Flatfile’s standard built-in constraints. Use cases include:
- Field-level validation based on complex logic (e.g., checking a value’s format against a specific regular expression not available by default)
- Cross-field validation where the validity of one field depends on the value of another (e.g., ensuring ‘endDate’ is after ‘startDate’)
- Validating data against an external system or API (e.g., checking if a product SKU exists in an external database)
- Applying a single validation rule to multiple fields simultaneously
The plugin works by matching a validator
key in the blueprint with a corresponding handler registered in the listener.
Installation
Install the plugin using npm:
Configuration & Parameters
Configuration for this plugin is not set on the plugin itself, but within the Sheet’s blueprint configuration. The plugin reads this blueprint to apply the correct logic.
Field-Level Constraints
For field-level constraints (used with externalConstraint
), add a constraint object to a field’s constraints
array:
Parameter | Type | Required | Description |
---|---|---|---|
type | string | Yes | Must be set to ‘external’ to indicate it’s a custom validation rule |
validator | string | Yes | A unique name for your validator used to link the blueprint rule to the validation logic |
config | object | No | An arbitrary object containing any parameters or settings your validation logic needs |
Sheet-Level Constraints
For sheet-level constraints (used with externalSheetConstraint
), add a constraint object to the sheet’s top-level constraints
array:
Parameter | Type | Required | Description |
---|---|---|---|
type | string | Yes | Must be set to ‘external’ |
validator | string | Yes | A unique name for your sheet-level validator |
fields | string[] | Yes | An array of field keys that this constraint applies to |
config | object | No | An arbitrary object with settings for your validation logic |
Default Behavior
If no external
type constraints are defined in the blueprint, the plugin will have no effect. The validation logic only runs when a matching validator
is found in the blueprint for the current sheet.
Usage Examples
Basic Field-Level Constraint
Configurable Constraint
Sheet-Level Constraint
API Reference
externalConstraint
Registers a listener for a field-level custom validation rule. The provided callback function will be executed for every record on each field that has a matching external
constraint in the blueprint.
Signature:
Parameters:
validator
(string): The name of the validator. This must match thevalidator
property in the field’s constraint configuration in the blueprint.cb
(function): A callback function that contains the validation logic. It receives:value
(any): The value of the cell being validatedkey
(string): The key of the field being validatedsupport
(object): An object containing helpful context:config
(any): Theconfig
object from the blueprint constraintrecord
(FlatfileRecord): The full record object, which can be used to get other values or add errorsproperty
(Flatfile.Property): The full property (field) definition from the sheet schemaevent
(FlatfileEvent): The raw event that triggered the validation
Error Handling Examples:
externalSheetConstraint
Registers a listener for a sheet-level custom validation rule that involves multiple fields. The callback is executed once per record for each matching external
constraint in the sheet’s top-level constraints
array.
Signature:
Parameters:
validator
(string): The name of the validator. This must match thevalidator
property in the sheet’s constraint configuration.cb
(function): A callback function that contains the validation logic. It receives:values
(Record<string, TRecordValue>): An object where keys are the field keys from the constraint’sfields
array and values are the corresponding cell values for the current recordkeys
(string[]): An array of the field keys this constraint applies to (from thefields
property in the blueprint)support
(object): An object containing helpful context:config
(any): Theconfig
object from the blueprint constraintrecord
(FlatfileRecord): The full record objectproperties
(Flatfile.Property[]): An array of the full property (field) definitions for the fields involved in this constraintevent
(FlatfileEvent): The raw event that triggered the validation
Error Handling Examples:
Troubleshooting
- Validator Not Firing: Ensure the
validator
string in your blueprint constraint exactly matches the string you passed toexternalConstraint
orexternalSheetConstraint
in your listener. - Constraint Not Recognized: Double-check that the constraint object in your blueprint has
type: 'external'
. - Sheet Constraint Issues: For
externalSheetConstraint
, make sure the sheet-level constraint in the blueprint includes thefields
array, listing the keys of all fields involved in the validation.
Notes
Special Considerations
- The plugin fetches and caches the sheet schema (blueprint) once per data submission (
commit:created
event). For very high-frequency operations, this could be a performance consideration, but for most use cases, it is not an issue. - The plugin relies on
@flatfile/plugin-record-hook
to process records in bulk.
Error Handling Patterns
The plugin supports two primary error handling patterns within the validation callback:
- Imperative: Call
record.addError(key, message)
to add an error to a specific field. This is useful for sheet-level constraints where you might want to flag only one of the involved fields. - Declarative:
throw new Error(message)
orthrow "message"
. The plugin will catch the thrown error. ForexternalConstraint
, the error is added to the field being validated. ForexternalSheetConstraint
, the same error message is added to all fields listed in the constraint’sfields
array.