When embedding Flatfile, this plugin should be deployed in a server-side listener. Learn more

Parameters

sheetSlug
string

The sheetSlug parameter is the slug of the sheet you want to listen to.

callback
function

The callback parameter takes a function that will be run on the record or records.

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.

Imported NPM Packages

Usage

install
npm i @flatfile/plugin-record-hook @flatfile/hooks

Import

import { FlatfileRecord, recordHook } from "@flatfile/plugin-record-hook";
import { FlatfileEvent, FlatfileListener } from "@flatfile/listener";

Pass recordHook or bulkRecordHook to a Flatfile data listener and provide a function to run when data is added or updated.

Listen for data changes

Set up a listener to configure Flatfile and respond to data Events. Then use this plugin to set up a hook that responds to data changes.

import { recordHook } from "@flatfile/plugin-record-hook";

export default async function (listener) {
  listener.use(
    recordHook("my-sheet", (record) => {
      //do your work here
      return record;
    })
  );
}

Additional Options

bulkRecordHook can accept additional properties. Props will be passed along to the transformer.

import { bulkRecordHook } from "@flatfile/plugin-record-hook";

export default async function (listener) {
  listener.use(
    bulkRecordHook("my-sheet", (records) => {
      return records.map((r) => {
        //do your work here
        return r;
      });
    }),
    { chunkSize: 100, parallel: 2 }
  );
}

Flexible Options

chunkSize
Default: "10_000"
number

Define how many records you want to process in each batch. This allows you to balance efficiency and resource utilization based on your specific use case.

parallel
Default: "1"
number

Choose whether the records should be processed in parallel. This enables you to optimize the execution time when dealing with large datasets.

Example Usage

This example sets up a record hook using listener.use to modify records in the “my-sheet” sheet.

When a record is processed by the hook, it checks if an email address is missing, empty, or invalid, and if so, it logs corresponding error messages and adds them to a form validation context (if the r object is related to form validation). This helps ensure that only valid email addresses are accepted in the application.

In the bulkRecordHook example, it passes a chunkSize of 100 and asks the hooks to run 2 at a time via the parallel property.

import { recordHook } from "@flatfile/plugin-record-hook";

export default async function (listener) {
  listener.use(
    recordHook(
      "my-sheet",
      (record) => {
        const email = record.get("email") as string;
        if (!email) {
          console.log("Email is required");
          record.addError("email", "Email is required");
        }
        const validEmailAddress = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
        if (email !== null && !validEmailAddress.test(email)) {
          console.log("Invalid email address");
          record.addError("email", "Invalid email address");
        }
        return record;
      }
    )
  );
}

See the code