Custom Scripts

What it is

Some transformations cannot be expressed with a fixed value or a built-in conversion: joining data from another collection, calling an external API, normalizing a value with your own rules. For those cases Fuego lets you write a custom script — a small piece of JavaScript executed by an embedded engine inside the app, once per document.

Custom scripts are available in five flows:

In every flow, returning undefined means “do nothing here”: leave the document unchanged (update), omit the document or user (export), or skip the row (import).

Writing a script

Scripts are written as a body: statements and a top-level return, no function wrapper needed. await is allowed.

const data = doc.data();
if (!data.email) return FieldValue.delete();
return data.email.trim().toLowerCase();

Two rules to keep in mind:

• Only the async APIs provided by Fuego (db, database(), fetch) actually resolve. setTimeout does not exist, and awaiting any other promise source fails the script with “script did not resolve synchronously”.
• Each invocation has a 30 second timeout.

The editor is a full Monaco editor with autocomplete for every injected global, and syntax errors are checked live by the same engine that runs the job.

You are not left guessing what is available:

• Every script editor starts with a foldable comment header documenting the globals of that flow, with examples — fold it away once you know the API.
• The question-mark button above the editor opens the Script reference dialog, listing the data available in this script, the available functions and complete examples.
• The folder button opens the Manage scripts dialog (see Script library below).

The Test button at the bottom of every editor runs the script against real data without writing anything — see Testing a script below.

Testing a script

Every script editor — inline and fullscreen — has a Test button at the bottom. It opens a dialog that runs the script against the first documents the job would process: up to 10, or fewer if the query has a smaller limit. For the import flow, the test runs against the first rows of the import file, parsed exactly like the real import — including CSV “skip conversion” columns — and empty rows are reported as errors, just as in the real job.

Each row of the result shows the document (or row) path and one of:

• the script’s output, rendered as JSON;
• a Skipped tag, when the script returned undefined;
• the error message, when the script failed on that document.

Database writes are always disabled during a test, so a test never touches your data. A re-run button executes the test again after you edit the script.

For exports the test shapes data exactly like the real export before running the script: with Anonymize data enabled it masks the values (scripts never see unmasked ones), and with Include all attributes off it narrows the row to the picked attributes. The preview therefore matches the exported file.

In the users flows the test works the same way: the users export test runs against the first 10 users of the selected tenant, with each row shaped by the current export options; the users import test runs against the first 10 rows of the file, and also shows the error the import would report for each transformed row. Writes stay disabled here too.

Globals per flow

Each flow injects its own inputs on top of the common globals:

doc behaves like a Firestore DocumentSnapshot: doc.id, doc.exists, doc.ref, doc.data(), doc.get('a.b'), and doc.createTime / doc.updateTime / doc.readTime as Date.

Firebase Authentication users

The same transform scripts are available in the users export and import jobs: enable Transform each user with a custom script in the Export users or Import users dialog.

// Only active users, with a claim-derived column
if (user.disabled) return undefined;
return { ...data, admin: !!get(user, 'customClaims.admin') };

// Normalize emails and skip rows without one
if (!data.email) return undefined;
return { ...data, email: data.email.trim().toLowerCase() };

Common globals

These are available in every script, in every flow.

// Queries
const snap = await db
  .collection('users')
  .where('age', '>=', 18)
  .orderBy('name')
  .limit(10)
  .select('name', 'email')
  .get(); // QuerySnapshot: .docs, .empty, .size, .forEach

const one = await db.doc('users/u1').get(); // DocumentSnapshot
const group = await db.collectionGroup('posts').where('draft', '==', false).get();

// Writes
await db.collection('logs').add({ at: new Date() });
await db.doc('users/u1').set({ active: true }, { merge: true });
await db.doc('users/u1').update({ 'stats.visits': 10 });
await db.doc('users/u1').delete();

const staging = database('staging');
const snap = await staging.collection('users').get();

const res = await fetch('https://api.example.com/rates', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ currency: 'EUR' }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const rates = await res.json(); // also: await res.text(), res.headers.get('x-…')

get(data, 'profile.full_name', '');              // safe deep read with a default
return pick(data, 'title', 'owner.email');       // keep only the listed paths
return { ...omit(data, 'internalNotes'), exportedAt: new Date() };

How values map to JavaScript

Firestore values arrive in the script as their natural JavaScript counterpart:

When writing back, whole JavaScript numbers are written as integers — unless the stored field is a double, in which case the type is preserved on update.

Limits

Error policy

Every job with a script has an If the script fails on a document setting:

• Skip the document and continue (default) — failures are counted, and the job details list every failed document with its path and the error message.
• Stop the job — the first failure aborts the whole job.

The users export and import jobs have the same setting, worded per user: If the script fails on a user, with Skip the user and continue or Stop the job.

Script library

Scripts can be saved and reused across jobs:

• Save to library stores the current script under a name.
• Load script… opens the library from any of the script dialogs; the picker only shows scripts saved for the same flow.

Related

• Bulk update documents
• Export collections
• Import data
• User import and export
• Anonymization
• Synchronization