@bernierllc/csv-mapper

Intelligent column mapping functionality for CSV data with field variations, auto-mapping, and type conversion.

Features

• Column Mapping: Map CSV columns to structured field names
• Field Variations: Handle multiple possible column names for the same field
• Auto-Mapping: Intelligent column name matching and suggestions
• Type Conversion: Convert string data to appropriate types
• Mapping Validation: Validate mapping configurations
• Bulk Operations: Process entire datasets with mapping rules

Installation

npm install @bernierllc/csv-mapper

Quick Start

Basic Column Mapping

import { CSVMapper, FieldType } from '@bernierllc/csv-mapper';

const mapper = new CSVMapper();

const mapping = {
  'email_address': { targetField: 'email', type: FieldType.EMAIL },
  'first_name': { targetField: 'firstName', type: FieldType.STRING },
  'last_name': { targetField: 'lastName', type: FieldType.STRING },
  'phone': { targetField: 'phone', type: FieldType.PHONE },
  'dob': { targetField: 'dateOfBirth', type: FieldType.DATE }
};

const csvRow = ['[email protected]', 'John', 'Doe', '555-1234', '1990-01-01'];
const mappedRow = mapper.mapRow(csvRow, mapping);

// Result: {
//   email: '[email protected]',
//   firstName: 'John',
//   lastName: 'Doe',
//   phone: '5551234',
//   dateOfBirth: Date('1990-01-01')
// }

Auto-Mapping

const headers = ['email_address', 'first_name', 'last_name', 'phone_number'];
const targetFields = ['email', 'firstName', 'lastName', 'phone'];

// Generate mapping suggestions
const suggestions = mapper.suggestMapping(headers, targetFields);
console.log(suggestions);
// [
//   { csvColumn: 'email_address', targetField: 'email', confidence: 0.95, reasoning: 'Field variation' },
//   { csvColumn: 'first_name', targetField: 'firstName', confidence: 0.95, reasoning: 'Field variation' },
//   ...
// ]

// Auto-generate mapping
const autoMapping = mapper.autoMap(headers, targetFields);

Bulk Processing

const csvRows = [
  ['[email protected]', 'John', 'Doe', '555-1234'],
  ['[email protected]', 'Jane', 'Smith', '555-5678']
];

const mappedRows = mapper.mapRows(csvRows, mapping);

API Reference

CSVMapper

Main class for CSV mapping operations.

Constructor

new CSVMapper(config?: MapperConfig)

Methods

• mapRow(row: string[], mapping: ColumnMapping): MappedRow
• mapRows(rows: string[][], mapping: ColumnMapping): MappedRow[]
• suggestMapping(headers: string[], targetFields: string[]): MappingSuggestion[]
• autoMap(headers: string[], targetFields: string[]): ColumnMapping
• validateMapping(mapping: ColumnMapping, headers: string[]): ValidationResult

Field Types

Supported field types for data conversion:

• FieldType.STRING - String values
• FieldType.NUMBER - Numeric values
• FieldType.BOOLEAN - Boolean values
• FieldType.DATE - Date values
• FieldType.EMAIL - Email addresses
• FieldType.PHONE - Phone numbers
• FieldType.URL - URLs
• FieldType.JSON - JSON data

Field Variations

Built-in field variations handle common CSV column name variations:

• email → ['email', 'e-mail', 'email_address', 'emailaddress', 'mail']
• firstName → ['first_name', 'firstname', 'first name', 'fname', 'given_name']
• lastName → ['last_name', 'lastname', 'last name', 'lname', 'family_name']
• And many more...

Advanced Usage

Custom Field Variations

import { FieldVariationManager } from '@bernierllc/csv-mapper';

// Add custom variations
FieldVariationManager.addVariations('customField', ['custom_field', 'customfield', 'cf']);

// Get variations for a field
const variations = FieldVariationManager.getVariations('email');

Type Conversion

import { TypeConverter, FieldType } from '@bernierllc/csv-mapper';

// Convert values
const result = TypeConverter.convert('[email protected]', FieldType.EMAIL);
console.log(result); // { value: '[email protected]', isValid: true }

// Infer types
const inferredType = TypeConverter.inferType('123.45');
console.log(inferredType); // FieldType.NUMBER

Configuration

const mapper = new CSVMapper({
  caseSensitive: false,
  fuzzyMatching: true,
  fuzzyThreshold: 0.7,
  enableAutoMapping: true,
  strictMode: false
});

Error Handling

The mapper provides detailed error information:

const mappedRow = mapper.mapRow(csvRow, mapping);

if (mappedRow._mappingErrors) {
  console.log('Mapping errors:', mappedRow._mappingErrors);
  // [
  //   {
  //     column: 'email_address',
  //     field: 'email',
  //     error: 'Invalid email format',
  //     value: 'invalid-email'
  //   }
  // ]
}

Performance

Optimized for large datasets:

• Small files (< 1MB): < 100ms processing time
• Medium files (1-10MB): < 1s processing time
• Large files (> 10MB): < 10s processing time

License

Bernier LLC - All rights reserved.