bridgelist

A TypeScript-based tool for automatically documenting field mappings between different API systems. Generate documentation from your mapping code using simple decorators.

Installation

npm install bridgelist
# or
yarn add bridgelist
# or
pnpm add bridgelist

Features

• Automatic Mapping Detection: Analyzes your TypeScript code to identify mapping relationships
• Decorator-based Configuration: Add metadata to your mapping methods
• HTML Documentation Generation: Creates clear and interactive documentation
• Supports Various Mapping Types:
  • Direct mappings
  • Transformations
  • Constant values
  • Nested objects

Usage

Basic Usage

1. Import the necessary functions:

import { GenerateMappingDocumentation, generateDocumentation } from 'bridgelist';

2. Extend tsconfig.json settings

{
  "compilerOptions": {
    
    "experimentalDecorators": true
    
  }
}

3. Decorate your mapping methods:

class SimpleMapper {
  @GenerateMappingDocumentation({
    sourceSystem: 'System A',
    targetSystem: 'System B',
    description: 'Converts customer data from System A to System B'
  })
  mapCustomer(sourceData: any): any {
    return {
      id: sourceData.id,
      firstName: sourceData.properties.firstname,
      lastName: sourceData.properties.lastname,
      // more mappings...
    };
  }
}

4. Generate the documentation:

// Scans the project and creates HTML documentation
generateDocumentation('./docs/api-mappings.html');

Complex Mappings

The tool automatically recognizes different types of mappings:

class ComplexMapper {
  @GenerateMappingDocumentation({
    sourceSystem: 'CRM',
    targetSystem: 'ERP',
    description: 'Converts CRM contacts to ERP customers'
  })
  mapContactToCustomer(contact: any): any { 
    return {
      // Direct mapping
      customerId: contact.id,
    
      // Constant value
      defaultCountry: 'Germany',
    
      // Transformation
      fullName: `${contact.firstName} ${contact.lastName}`,
    
      // Nested object
      address: {
        street: contact.address.streetName,
        city: contact.address.city,
        country: defaultCountry
      }
    };
  }
}

API Reference

GenerateMappingDocumentation(options)

A decorator to mark mapping methods with metadata.

Parameters

• options: An object with the following properties:
  • sourceSystem (string, required): Name of the source system
  • targetSystem (string, required): Name of the target system
  • description (string, optional): Description of the mapping

generateDocumentation(outputPath)

Scans the project for decorated methods and generates HTML documentation.

Parameters

• outputPath (string, required): Path where the HTML documentation should be saved

scanProject(rootDir)

Recursively scans a directory for TypeScript files with decorated mapping methods.

Parameters

• rootDir (string, required): Path to the root directory of the project to scan