Binding Transforms

When to Use Transforms

Registering a Transform

import { registerBindingTransform } from '@atlas-forms/form-engine-js';

// Register once at application startup
registerBindingTransform('isoToLocaleDate', (value: string): string => {
  if (!value) return '';
  const date = new Date(value);
  return date.toLocaleDateString('en-GB', { day: '2-digit', month: 'short', year: 'numeric' });
  // e.g. '15 Jan 2026'
});

registerBindingTransform('localeDateToIso', (value: string): string => {
  if (!value) return '';
  // Parse '15 Jan 2026' → '2026-01-15'
  const date = new Date(value);
  return date.toISOString().split('T')[0];
});

registerBindingTransform('centsToGbp', (value: number): number => {
  return typeof value === 'number' ? value / 100 : 0;
});

registerBindingTransform('gbpToCents', (value: number): number => {
  return typeof value === 'number' ? Math.round(value * 100) : 0;
});

Using Transforms in a Schema

// Date field: stored as ISO, displayed as locale date
{
  "id":   "contract-start",
  "type": "date-picker",
  "label": "Contract Start Date",
  "binding": {
    "source": "$json",
    "path":   "contract.startDate",
    "transform": {
      "read":  "isoToLocaleDate",
      "write": "localeDateToIso"
    }
  }
}

// Amount field: stored in cents, displayed in pounds
{
  "id":   "invoice-amount",
  "type": "number",
  "label": "Invoice Amount (£)",
  "binding": {
    "source": "$json",
    "path":   "invoice.amountPence",
    "transform": {
      "read":  "centsToGbp",
      "write": "gbpToCents"
    }
  }
}

One-Directional Transforms

You can apply only a read transform (display formatting without write-back conversion) or only a write transform:

// Read-only display transform: show a code as a human-readable label
{
  "binding": {
    "source": "$json",
    "path":   "statusCode",
    "transform": {
      "read": "statusCodeToLabel"   // write omitted — raw code is saved on submit
    }
  }
}

Transform Function Signature

type BindingTransformFn = (value: any) => any;

// Transforms must be pure functions — no side effects
// They may receive undefined/null and should handle gracefully
registerBindingTransform('myTransform', (value) => {
  if (value == null) return '';   // Safe null handling
  return String(value).toUpperCase();
});