@bernierllc/data-transformer

Generic schema mapping execution for JSON/API data transformation.

Features

• 🔄 Transform data using schema mappings - Define source-to-target field mappings with type conversion
• 🎯 Type conversion - Convert between text, number, date, and boolean types
• 📝 Field name normalization - Support for camelCase, snake_case, kebab-case, and PascalCase
• ✅ Mapping validation - Validate mappings before transformation
• 🐛 Error reporting - Detailed error and warning messages
• 📦 Supports arrays - Transform single objects or arrays of objects

Installation

npm install @bernierllc/data-transformer

Usage

Basic Transformation

import { DataTransformer, SchemaMapping } from '@bernierllc/data-transformer';

const transformer = new DataTransformer();

const mapping: SchemaMapping[] = [
  { sourceField: 'PROJECT_ID', targetField: 'externalId', dataType: 'text' },
  { sourceField: 'TOWN', targetField: 'address', dataType: 'text' },
  { sourceField: 'AD_DATE', targetField: 'permitDate', dataType: 'date' },
  { sourceField: 'TOTAL_COST', targetField: 'cost', dataType: 'number' }
];

const data = {
  PROJECT_ID: '608923',
  TOWN: 'BOSTON',
  AD_DATE: '2023-05-15',
  TOTAL_COST: 15000000
};

const result = transformer.transform(data, mapping);

console.log(result.data);
// {
//   externalId: '608923',
//   address: 'BOSTON',
//   permitDate: '2023-05-15T00:00:00.000Z',
//   cost: 15000000
// }

Transformation Rules

Apply advanced transformation rules:

const mapping: SchemaMapping[] = [
  {
    sourceField: 'name',
    targetField: 'fullName',
    dataType: 'text',
    transformation: {
      trim: true,
      defaultValue: 'Unknown'
    }
  },
  {
    sourceField: 'cost',
    targetField: 'amount',
    dataType: 'number',
    transformation: {
      parseAs: 'int' // or 'float'
    }
  },
  {
    sourceField: 'date',
    targetField: 'createdAt',
    dataType: 'date',
    transformation: {
      format: 'YYYY-MM-DD' // or 'ISO8601', 'MM/DD/YYYY'
    }
  }
];

Array Transformation

Transform arrays of objects:

const data = [
  { name: 'John', age: '30' },
  { name: 'Jane', age: '25' }
];

const mapping: SchemaMapping[] = [
  { sourceField: 'name', targetField: 'fullName', dataType: 'text' },
  { sourceField: 'age', targetField: 'userAge', dataType: 'number' }
];

const result = transformer.transform(data, mapping);

console.log(result.data);
// [
//   { fullName: 'John', userAge: 30 },
//   { fullName: 'Jane', userAge: 25 }
// ]

Error Handling

const result = transformer.transform(data, mapping);

if (result.errors.length > 0) {
  console.error('Transformation errors:', result.errors);
  // [{ field: 'userAge', message: 'Cannot convert "abc" to number', value: 'abc' }]
}

if (result.warnings.length > 0) {
  console.warn('Transformation warnings:', result.warnings);
  // [{ field: 'address', message: 'Source field "TOWN" not found in data', value: undefined }]
}

Mapping Validation

Validate mappings before transformation:

const validation = transformer.validateMapping(mapping);

if (!validation.valid) {
  console.error('Invalid mapping:', validation.errors);
}

if (validation.warnings.length > 0) {
  console.warn('Mapping warnings:', validation.warnings);
}

Field Name Normalization

// Convert field names to different cases
const camelCase = transformer.normalizeFieldName('PROJECT_ID', 'camel');
// 'projectId'

const snakeCase = transformer.normalizeFieldName('projectId', 'snake');
// 'project_id'

const kebabCase = transformer.normalizeFieldName('projectId', 'kebab');
// 'project-id'

const pascalCase = transformer.normalizeFieldName('project_id', 'pascal');
// 'ProjectId'

Type Conversion

// Convert individual values
const numberValue = transformer.applyTypeConversion('123', 'number');
// 123

const dateValue = transformer.applyTypeConversion('2023-05-15', 'date', {
  format: 'YYYY-MM-DD'
});
// '2023-05-15'

const booleanValue = transformer.applyTypeConversion('true', 'boolean');
// true

const textValue = transformer.applyTypeConversion('  hello  ', 'text', {
  trim: true
});
// 'hello'

API

DataTransformer

transform(data, mapping): TransformResult

Transform data using schema mappings.

• data: Single object or array of objects to transform
• mapping: Array of schema mappings
• Returns: TransformResult with data, errors, and warnings

applyTypeConversion(value, dataType, options?): any

Apply type conversion to a value.

• value: Value to convert
• dataType: Target data type ('text', 'number', 'date', 'boolean')
• options: Optional transformation rules
• Returns: Converted value

normalizeFieldName(name, targetCase): string

Normalize field name to target case.

• name: Field name to normalize
• targetCase: Target case format ('camel', 'snake', 'kebab', 'pascal')
• Returns: Normalized field name

validateMapping(mapping): ValidationResult

Validate mapping configuration.

• mapping: Schema mappings to validate
• Returns: ValidationResult with valid, errors, and warnings

Types

SchemaMapping

interface SchemaMapping {
  sourceField: string;
  targetField: string;
  dataType: 'text' | 'number' | 'date' | 'boolean';
  transformation?: TransformationRule;
}

TransformationRule

interface TransformationRule {
  defaultValue?: any;
  format?: string; // For dates: 'ISO8601', 'YYYY-MM-DD', 'MM/DD/YYYY'
  trim?: boolean; // For text
  parseAs?: 'int' | 'float'; // For numbers
}

TransformResult

interface TransformResult {
  data: any;
  errors: TransformError[];
  warnings: TransformWarning[];
}

TransformError / TransformWarning

interface TransformError {
  field: string;
  message: string;
  value: any;
}

Design Philosophy

This package follows MECE (Mutually Exclusive, Collectively Exhaustive) principles:

• Mutually Exclusive: Handles generic JSON/object transformation, distinct from CSV-specific operations (@bernierllc/csv-mapper)
• Collectively Exhaustive: Covers all generic data transformation needs

What This Package Does

✅ Generic schema mapping execution for JSON/objects ✅ Type conversion (text, number, date, boolean) ✅ Field name normalization ✅ Mapping validation ✅ Error handling and reporting

What This Package Does NOT Do

❌ CSV parsing/reading (use @bernierllc/csv-mapper) ❌ Domain-specific business logic ❌ Data access/storage ❌ Generic validation (use @bernierllc/schema-validator)

License

Copyright (c) 2025 Bernier LLC. See LICENSE file for details.