@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

``bash
npm install @bernierllc/data-transformer
`

Usage

$3

`typescript
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
// }
`

$3

Apply advanced transformation rules:

`typescript
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'
}
}
];
`

$3

Transform arrays of objects:

`typescript
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 }
// ]
`

$3

`typescript
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 }]
}
`

$3

Validate mappings before transformation:

`typescript
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);
}
`

$3

`typescript
// 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'
`

$3

`typescript
// 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

$3

#### 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

$3

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

$3

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

$3

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

$3

`typescript
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

$3

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

$3

❌ 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.