@expeed/ngx-data-mapper

A visual drag-and-drop data mapping component for Angular applications. Create field mappings between source and target JSON schemas with transformations, array mapping, and default values.

Features

• Drag & Drop Mapping: Visually connect source fields to target fields
• Multi-Source Mapping: Combine multiple source fields into one target (concatenation)
• Transformations: Apply data transformations (uppercase, lowercase, trim, date formatting, number formatting, substring, replace, mask, templating)
• Array Mapping: Map array fields with optional filtering
• Array-to-Object: Select single item from array using first, last, or conditional logic
• Default Values: Set defaults for unmapped target fields
• Endpoint Dragging: Reassign mappings by dragging connection endpoints
• Real-time Preview: View transformations with sample data
• Import/Export: Save and load mappings as JSON

Installation

npm install @expeed/ngx-data-mapper

Peer Dependencies

npm install @angular/cdk @angular/material

Usage

Basic Usage

import { Component } from '@angular/core';
import { DataMapperComponent, JsonSchema, FieldMapping } from '@expeed/ngx-data-mapper';

@Component({
  selector: 'app-mapper',
  standalone: true,
  imports: [DataMapperComponent],
  template: `
    <data-mapper
      [sourceSchema]="sourceSchema"
      [targetSchema]="targetSchema"
      [sampleData]="sampleData"
      (mappingsChange)="onMappingsChange($event)"
    />
  `
})
export class MapperComponent {
  sourceSchema: JsonSchema = {
    type: 'object',
    title: 'Source',
    properties: {
      firstName: { type: 'string', title: 'First Name' },
      lastName: { type: 'string', title: 'Last Name' },
      birthDate: { type: 'string', format: 'date', title: 'Birth Date' }
    }
  };

  targetSchema: JsonSchema = {
    type: 'object',
    title: 'Target',
    properties: {
      fullName: { type: 'string', title: 'Full Name' },
      age: { type: 'integer', title: 'Age' }
    }
  };

  sampleData = {
    firstName: 'John',
    lastName: 'Doe',
    birthDate: '1990-05-15'
  };

  onMappingsChange(mappings: FieldMapping[]): void {
    console.log('Mappings:', mappings);
  }
}

With Schema Document (Multiple Definitions)

import { SchemaDocument } from '@expeed/ngx-data-mapper';

sourceSchema: SchemaDocument = {
  $defs: {
    Customer: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        email: { type: 'string' }
      }
    }
  }
};

// Reference specific definition
sourceSchemaRef = '#/$defs/Customer';

<data-mapper
  [sourceSchema]="sourceSchema"
  [targetSchema]="targetSchema"
  [sourceSchemaRef]="sourceSchemaRef"
  [targetSchemaRef]="targetSchemaRef"
  (mappingsChange)="onMappingsChange($event)"
/>

Import/Export Mappings

import { ViewChild } from '@angular/core';
import { DataMapperComponent } from '@expeed/ngx-data-mapper';

@ViewChild(DataMapperComponent) mapper!: DataMapperComponent;

exportMappings(): void {
  const json = this.mapper.exportMappings();
  // Save to file or API
}

importMappings(json: string): void {
  this.mapper.importMappings(json);
}

clearMappings(): void {
  this.mapper.clearAllMappings();
}

API Reference

DataMapperComponent

Inputs

| Input | Type | Default | Description | |-------|------|---------|-------------| | sourceSchema | JsonSchema \| SchemaDocument | - | Source schema definition | | targetSchema | JsonSchema \| SchemaDocument | - | Target schema definition | | sourceSchemaRef | string | - | JSON pointer to source definition (e.g., #/$defs/Source) | | targetSchemaRef | string | - | JSON pointer to target definition (e.g., #/$defs/Target) | | sampleData | Record<string, unknown> | {} | Sample data for transformation preview |

Outputs

| Output | Type | Description | |--------|------|-------------| | mappingsChange | EventEmitter<FieldMapping[]> | Emits when mappings change |

Public Methods

| Method | Returns | Description | |--------|---------|-------------| | exportMappings() | string | Export all mappings as JSON | | importMappings(json: string) | void | Import mappings from JSON | | clearAllMappings() | void | Remove all mappings |

Transformations

Available transformation types:

| Type | Description | Example | |------|-------------|---------| | uppercase | Convert to uppercase | "hello" → "HELLO" | | lowercase | Convert to lowercase | "HELLO" → "hello" | | trim | Remove whitespace | " hello " → "hello" | | concat | Concatenate multiple fields | "John" + "Doe" → "John Doe" | | substring | Extract part of string | "hello"[0:3] → "hel" | | replace | Replace text | "hello" → "hi" | | mask | Mask characters | "1234567890" → "******7890" | | dateFormat | Format date | "2024-01-15" → "Jan 15, 2024" | | numberFormat | Format number | 1234.5 → "1,234.50" | | template | Template string | "${firstName} ${lastName}" | | datePart | Extract date part | Extract year, month, day |

Array Mapping

Array to Array

Map arrays with optional filtering:

// Filter array items
{
  type: 'array-mapping',
  filter: {
    conditions: [
      { field: 'status', operator: 'equals', value: 'active' }
    ]
  }
}

Array to Object

Select single item from array:

| Mode | Description | |------|-------------| | first | Select first item | | last | Select last item | | condition | Select item matching condition |

Default Values

Set default values for unmapped target fields:

| Type | Description | |------|-------------| | static | Fixed value | | null | Null value | | empty-string | Empty string | | empty-array | Empty array [] | | empty-object | Empty object {} | | current-date | Current date | | current-datetime | Current date and time | | uuid | Generated UUID |

Styling

Customize appearance with CSS custom properties:

data-mapper {
  --data-mapper-bg: #f8fafc;
  --data-mapper-panel-bg: #ffffff;
  --data-mapper-text-primary: #1e293b;
  --data-mapper-text-secondary: #64748b;
  --data-mapper-accent-primary: #6366f1;
  --data-mapper-connector-color: #6366f1;
  --data-mapper-border-color: #e2e8f0;
}

Dark Theme

data-mapper {
  --data-mapper-bg: #1e293b;
  --data-mapper-panel-bg: #334155;
  --data-mapper-text-primary: #f1f5f9;
  --data-mapper-text-secondary: #cbd5e1;
  --data-mapper-accent-primary: #818cf8;
  --data-mapper-connector-color: #818cf8;
  --data-mapper-border-color: #475569;
}

Exports

// Components
export { DataMapperComponent } from './lib/components/data-mapper/data-mapper.component';
export { SchemaTreeComponent } from './lib/components/schema-tree/schema-tree.component';

// Services
export { MappingService } from './lib/services/mapping.service';
export { TransformationService } from './lib/services/transformation.service';
export { SchemaParserService } from './lib/services/schema-parser.service';
export { SvgConnectorService } from './lib/services/svg-connector.service';

// Types
export { JsonSchema, SchemaDocument } from './lib/models/json-schema.model';
export { FieldMapping, FieldReference } from './lib/models/field-mapping.model';
export { TransformationConfig, TransformationType } from './lib/models/transformation.model';
export { ArrayMapping, ArrayToObjectMapping } from './lib/models/array-mapping.model';
export { DefaultValue, DefaultValueType } from './lib/models/default-value.model';
export { SchemaTreeNode, FieldType } from './lib/models/schema-tree.model';

Requirements

• Angular 19+
• Angular Material 19+
• Angular CDK 19+

License

Apache 2.0