# @flatfile/plugin-autocast

> A plugin for automatically casting values in Flatfile.

Latest version **7.0.0** (published 2025-01-10) · ISC license · 0 weekly downloads

## Install

```sh
npm install @flatfile/plugin-autocast
pnpm add @flatfile/plugin-autocast
yarn add @flatfile/plugin-autocast
bun add @flatfile/plugin-autocast
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 7.0.0 |
| Published | 2025-01-10 |
| First published | 2023-04-26 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >= 18 |
| Dependencies | 2 |
| Unpacked size | 41.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 7 |
| Author | Alex Hollenbeck |
| Maintainers | sarocu, dboskovic, nate.ferrero, jmmander, madmandrit, bangarang, carlbrugger, flatfileinfra, flatderek, bigcountrycrane, flatfilecolin, alnoor, rjhyde, sambarrowclough, meritmalling, mmccooyyy |
| Keywords | flatfile-plugins, category-transform, featured |

## Links

- npm: https://www.npmjs.com/package/@flatfile/plugin-autocast
- Repository: https://github.com/FlatFilers/flatfile-plugins
- Homepage: https://github.com/FlatFilers/flatfile-plugins#readme
- Issues: https://github.com/FlatFilers/flatfile-plugins/issues
- npm.io page: https://npm.io/package/@flatfile/plugin-autocast

## Dependencies (2)

- [@flatfile/hooks](https://npm.io/package/@flatfile/hooks.md) ^1.6.0
- [@flatfile/util-common](https://npm.io/package/@flatfile/util-common.md) ^1.6.0

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 7.0.0 (latest) — 2025-01-10
- 6.0.1 — 2024-12-10
- 6.0.0 — 2024-11-19
- 5.0.0 — 2024-11-07
- 4.0.0 — 2024-10-31
- 3.0.0 — 2024-10-29
- 2.0.1 — 2024-10-03
- 2.0.0 — 2024-09-24
- 1.0.1 — 2024-09-03
- 1.0.0 — 2024-05-28
- 0.8.2 — 2024-05-20
- 0.8.1 — 2024-04-30
- 0.8.0 — 2024-04-23
- 0.7.11 — 2024-04-12
- 0.7.10 — 2024-04-08
- … 27 more at https://npm.io/package/@flatfile/plugin-autocast/versions

## README

<!-- START_INFOCARD -->

# @flatfile/plugin-autocast
**Automatically cast values in Flatfile to their appropriate types with this plugin.**


The `@flatfile/plugin-autocast` plugin is an opinionated transformer that will
automatically convert the data in the Sheet to match the type defined by the
Blueprint.


**Event Type:**
`listener.on('commit:created')`


**Supported field types:**
`number`, `boolean`, `date`

<!-- END_INFOCARD -->


## Parameters

#### `sheetSlug` - `string` - (required)

The `sheetSlug` indicates the slug name of the sheet you want to monitor.

#### `fieldFilters` - `string[]`

Use the `fieldFilters` parameter to select specific fields to monitor. Without
any specified `fieldFilters`, the plugin will automatically monitor
all castable fields, including strings, numbers, booleans, and dates.


#### `options.chunkSize` - `default: "10_000"` - `number`

The `chunkSize` parameter allows you to specify the quantity of records to in
each chunk.

#### `options.parallel` - `default: "1"` - `number`

The `parallel` parameter allows you to specify the number of chunks to process
in parallel.


## API Calls

- `api.sheets.get`


## Usage

The `autocast` plugin will listen for the `commit:created` event and cast strings, numbers, booleans,
and dates to the appropriate Blueprint type. Note that the `recordHook` and `bulkRecordHook` plugins
listen for the same event type. Plugins will fire in the order they are placed in the listener.

### Strings

Numbers and booleans are transformed from strings to their respective types (i.e., `'1'` to `1`, `"true"` to `true`).

### Numbers

String numbers (i.e `'1'`), string decimals (i.e `'1.1'`), and string numbers with commas (i.e `'1,000'`)
are interpreted as numbers.

### Booleans

`'1'`, `'yes'`, `'true'`, `'on'`, `'t'`, `'y'`, and `1` are interpreted as truthy values.

`'-1'`, `'0'`, `'no'`, `'false'`, `'off'`, `'f'`, `'n'`, `0`, `-1` are interpreted as falsy values.

### Dates

Date strings and numbers are cast to UTC strings. For example, `YYYY-MM-DD...` formats are treated as ISO 8601 dates (UTC), whereas other formats are considered local time and converted to UTC:

- `'2023-08-16'` => `'Wed, 16 Aug 2023 00:00:00 GMT'`
- `'08-16-2023'` => `'Wed, 16 Aug 2023 00:00:00 GMT'`
- `'08/16/2023'` => `'Wed, 16 Aug 2023 00:00:00 GMT'`
- `'Aug 16, 2023'` => `'Wed, 16 Aug 2023 00:00:00 GMT'`
- `'August 16, 2023'` => `'Wed, 16 Aug 2023 00:00:00 GMT'`
- `'2023-08-16T00:00:00.000Z'` => `'Wed, 16 Aug 2023 00:00:00 GMT'`
- `1692144000000` => `'Wed, 16 Aug 2023 00:00:00 GMT'`

**install**
```bash 
npm i @flatfile/plugin-autocast
```

**import**
```js 
import { autocast } from "@flatfile/plugin-autocast";
```

**listener.js**
```js 
listener.use(autocast("sheetSlug"));
```
**listener.js w/ fieldFilters**
```js 
listener.use(autocast("sheetSlug", ["numberField", "dateField"]));
```
**listener.js w/ fieldFilters & options**
```js 
listener.use(
  autocast("sheetSlug", ["numberField", "dateField"], {
    chunkSize: 10_000,
    parallel: 2,
  })
);
```

---
_Source: https://npm.io/package/@flatfile/plugin-autocast · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._