Transformers

This section describes available transformation functions.

Async transformers & run timing

Transformers may be synchronous or asynchronous. A custom transformFn may return either ImporterOutputFieldType | undefined or a Promise<ImporterOutputFieldType | undefined> — making it possible to transform a value by calling a remote service or an LLM.

By default, transformers run reactively on every edit (runOn: 'change'). For slow or costly async work you usually don’t want that to fire on each keystroke — set runOn: 'submit' so the transformer runs only in the final pass when the user submits:

{
  transformer: 'custom',
  key: 'normalize_with_llm',
  runOn: 'submit', // deferred — runs once on submit, not on every edit
  transformFn: async (value) => normalizeWithLlm(value),
}

Async calls are throttled so a large sheet can’t fire one request per cell at once; tune the cap with maxConcurrentAsyncOperations.

phone_number

Description:
Formats phone numbers to a standard format.

---

postal_code

Description:
Formats postal codes to a standard format.

---

state_code

Description:
Formats state codes to a standard format.

---

strip

Description:
Trims leading and trailing whitespace.

---

custom

Description:
Custom transformation function.

Additional:
Requires a key and a transformFn to modify the value.

Return undefined in transformFn to skip the transformation.