Autocast Plugin

The Autocast plugin is an opinionated transformer for Flatfile that automatically converts data in a Sheet to match the data types defined in the corresponding Blueprint (Schema). It operates on the commit:created event, meaning it processes records after they have been committed to the sheet.

Its primary purpose is to clean and standardize data by ensuring that values intended to be numbers, booleans, or dates are correctly typed, even if they are imported as strings. For example, it can convert the string “1,000” to the number 1000, the string “yes” to the boolean true, and the string “08/16/2023” to a standardized UTC date string.

This plugin is useful in any scenario where source data may have inconsistent or incorrect data types, saving developers from writing manual data-casting logic.

​

Installation

Install the plugin using npm:

npm install @flatfile/plugin-autocast

​

Configuration & Parameters

​

Main Plugin Function

The autocast function accepts the following parameters:

​

Usage Examples

​

Basic Usage

Apply autocasting to all supported fields on a sheet:

import { FlatfileListener } from '@flatfile/listener';
import { autocast } from '@flatfile/plugin-autocast';

const listener = new FlatfileListener();

listener.use(autocast('contacts'));

export default listener;

​

Targeted Field Casting

Apply autocasting to only specific fields:

import { FlatfileListener } from '@flatfile/listener';
import { autocast } from '@flatfile/plugin-autocast';

const listener = new FlatfileListener();

listener.use(autocast('contacts', ['annualRevenue', 'subscribed']));

export default listener;

​

Advanced Configuration

Configure field filters and adjust performance settings:

import { FlatfileListener } from '@flatfile/listener';
import { autocast } from '@flatfile/plugin-autocast';

const listener = new FlatfileListener();

listener.use(
  autocast('contacts', ['annualRevenue', 'subscribed'], {
    chunkSize: 5000,
    parallel: 2,
    debug: true,
  })
);

export default listener;

​

Using Utility Functions

The plugin also exports individual casting utility functions:

import { castNumber, castBoolean, castDate } from '@flatfile/plugin-autocast';

// Cast numbers (handles commas)
const num1 = castNumber('1,234.56'); // Returns 1234.56
const num2 = castNumber(99); // Returns 99

// Cast booleans
const bool1 = castBoolean('yes'); // Returns true
const bool2 = castBoolean(0); // Returns false
const bool3 = castBoolean('f'); // Returns false

// Cast dates
const date1 = castDate('08/16/2023'); // Returns 'Wed, 16 Aug 2023 00:00:00 GMT'
const date2 = castDate(1692144000000); // Returns 'Wed, 16 Aug 2023 00:00:00 GMT'

​

Troubleshooting

​

Error Handling with Utility Functions

The individual casting utility functions throw errors when values cannot be converted:

import { castNumber, castBoolean, castDate } from '@flatfile/plugin-autocast';

try {
  const invalidNum = castNumber('not a number');
} catch (e) {
  console.error(e.message); // Prints: Invalid number
}

try {
  const invalidBool = castBoolean('maybe');
} catch (e) {
  console.error(e.message); // Prints: Invalid boolean
}

try {
  const invalidDate = castDate('not a date');
} catch (e) {
  console.error(e.message); // Prints: Invalid date
}

​

Notes

​

Event Trigger

The plugin is designed to run on the listener.on('commit:created') event.

​

Plugin Order

This plugin runs on the same event as recordHook and bulkRecordHook. The order in which you .use() the plugins in your listener matters, as they will execute sequentially.

​

Error Handling Pattern

The main autocast plugin does not throw errors. Instead, if a value cannot be cast, it attaches an error message directly to the record’s cell using record.addError(). This makes the errors visible to the user in the Flatfile UI. The individual cast* utility functions, however, do throw an Error on failure.

​

Supported Types

The plugin automatically targets fields of type number, boolean, and date as defined in the Sheet’s Blueprint. It does not attempt to cast string fields by default.

​

Boolean Casting

• Truthy values: '1', 'yes', 'true', 'on', 't', 'y', and 1
• Falsy values: '-1', '0', 'no', 'false', 'off', 'f', 'n', 0, and -1

​

Date Casting

All parsed dates are converted to a standardized UTC string format. ISO 8601 formats like YYYY-MM-DD are treated as UTC, while other formats like MM/DD/YYYY are assumed to be local time and are converted to UTC.