Forem: hello-ediflow

Building EDIFlow - Presentation Layer: CLI, DI Container & Wiring (Part 5)

hello-ediflow — Mon, 11 May 2026 13:00:38 +0000

Series: Building EDIFlow - A Clean Architecture Journey in TypeScript (Part 5/6)
Reading Time: ~8 minutes

Recap — Where We Left Off

In Part 4, we implemented the Infrastructure Layer — EDIFACT/X12 parsers, builders, validators, the file-based repository, and 13 data packages with 126–319 message definitions each.

Now it's time for the outermost layer — the Presentation Layer. In EDIFlow, that's a CLI. But the patterns apply equally to a REST API, a web UI, or any other entry point.

┌─────────────────────────────────────────────┐
│  🔥 PRESENTATION (CLI)                      │  ← You are here
│  Commands · DI Container · Output           │
│  ┌───────────────────────────────────────┐  │
│  │  Infrastructure (Parsers, Repos)      │  │
│  │  ┌─────────────────────────────────┐  │  │
│  │  │  Application (Use Cases, Ports) │  │  │
│  │  │  ┌───────────────────────────┐  │  │  │
│  │  │  │  Domain (Entities)        │  │  │  │
│  │  │  └───────────────────────────┘  │  │  │
│  │  └─────────────────────────────────┘  │  │
│  └───────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

The Presentation Layer has one job: convert user input into Use Case calls, and Use Case output into user-friendly results.

Why a CLI? — The Fastest Way to Prove Your Architecture

Why did we build a CLI instead of a REST API or a web UI?

1. Zero-friction developer experience. A CLI lets any developer try EDIFlow in 10 seconds: npx @ediflow/cli parse invoice.edi. No server setup, no browser, no configuration. Just pipe in a file and get JSON out. For an open-source library that needs adoption, this is critical.

2. The ultimate integration test. The CLI exercises every single layer — from parsing raw bytes (Infrastructure) through Use Cases (Application) to formatted output (Presentation). If npx @ediflow/cli parse works, all four layers work. It's a vertical slice through the entire architecture.

3. Clean Architecture makes it replaceable. Because the CLI is just a thin wrapper around Use Cases, adding a REST API or a Lambda handler later is trivial — they'd call the same UseCaseFactory with the same DIContainer. The CLI doesn't contain business logic; it only translates command-line arguments into Use Case inputs.

4. Scripting & CI/CD. EDI processing often happens in automated pipelines — validate incoming files, convert to JSON, check against schemas. A CLI fits naturally into bash scripts, GitHub Actions, and cron jobs. A web UI doesn't.

In short: the CLI is the simplest possible Presentation Layer that proves Clean Architecture works end-to-end, while delivering immediate value to developers.

The DI Container — Where Everything Gets Wired

This is the single place where all layers connect. In a framework like NestJS, this would be a module with providers. In EDIFlow, it's a pure TypeScript class:

export class DIContainer {
  private static instance: DIContainer;
  public readonly useCaseFactory: UseCaseFactory;
  public readonly repository: IMessageStructureRepository;
  public readonly structureMappingService: StructureMappingService;

  private constructor() {
    // EDIFACT infrastructure
    const edifactParser = new EdifactMessageParser(
      new EdifactDelimiterDetector(),
      new EdifactTokenizer(),
      new EdifactSegmentParser()
    );
    const edifactBuilder = new EdifactMessageBuilder();

    // X12 infrastructure
    const x12Parser = new X12MessageParser(
      new X12DelimiterDetector(),
      new X12SegmentParser(),
      new X12EnvelopeParser()
    );
    const x12Builder = new X12MessageBuilder();

    // Register parsers and builders by standard
    const parsers = new Map([['EDIFACT', edifactParser], ['X12', x12Parser]]);
    const builders = new Map([['EDIFACT', edifactBuilder], ['X12', x12Builder]]);

    // Wire Application Layer
    const validationService = new EDIMessageValidationService();
    this.useCaseFactory = new UseCaseFactory(parsers, builders, validationService);
    this.repository = new FileBasedMessageStructureRepository(DATA_PACKAGES_BASE_PATH);
    this.structureMappingService = new StructureMappingService();
  }

  static getInstance(): DIContainer {
    if (!DIContainer.instance) {
      DIContainer.instance = new DIContainer();
    }
    return DIContainer.instance;
  }
}

Why a Singleton? The parsers and repository don't hold mutable state between calls. Creating them once and reusing them is safe and avoids repeated initialization of data package caches.

Why not a DI framework? Because we have ~10 dependencies. A framework like tsyringe or inversify would add complexity for a problem that a plain constructor solves.

The key insight: this is the only file that imports from all layers simultaneously. Domain doesn't know Infrastructure. Application doesn't know Infrastructure. Only this container does.

Commands — The User's Entry Point

Each CLI command follows the same pattern: parse input → call Use Case → format output.

ParseCommand — The Most Complex One

export class ParseCommand {
  constructor(
    private readonly useCaseFactory: UseCaseFactory,
    private readonly repository?: IMessageStructureRepository,
    private readonly structureMappingService?: StructureMappingService
  ) {}

  register(program: Command): void {
    program
      .command('parse')
      .argument('<file>', 'EDI file path')
      .option('--output-type <type>', 'edi-message | business-object')
      .option('--property-parse-mode <mode>', 'code | name | camelCase | snake_case | kebab-case')
      .action(async (file, options) => {
        await this.execute(file, options);
      });
  }

  async execute(file: string, options: any): Promise<void> {
    const content = readEDIFile(file);
    const standard = this.detectStandard(content); // UNA/UNB → EDIFACT, ISA → X12

    // Phase 1: Parse EDI → EDIMessage
    const parseUseCase = this.useCaseFactory.createParseUseCase(standard);
    const result = parseUseCase.execute({
      message: content,
      standard: this.parseStandard(standard),
    });

    if (!result.success) {
      throw new Error(ErrorHandler.formatMultiple(result.errors));
    }

    // Phase 2 (optional): EDIMessage → Business Object
    if (options.outputType === 'business-object' && this.repository) {
      const structure = await this.repository.getMessageStructure(
        standard, result.metadata.version.value, result.metadata.messageType.value
      );

      if (structure && this.structureMappingService) {
        const mappedUseCase = this.useCaseFactory.createParseUseCase(standard, this.structureMappingService);
        const mapped = mappedUseCase.execute({
          message: content,
          standard: this.parseStandard(standard),
          returnTypedObject: true,
          messageStructure: structure,
          mappingKeyStrategy: options.propertyParseMode || 'code',
        });

        this.writeOutput(mapped.businessObject, options);
        return;
      }
    }

    this.writeOutput(this.formatEDIMessageResult(result), options);
  }

  private detectStandard(content: string): string {
    if (content.startsWith('UNB') || content.startsWith('UNA')) return 'EDIFACT';
    if (content.startsWith('ISA')) return 'X12';
    throw new Error('Unable to detect EDI standard.');
  }
}

What's happening here:

Auto-detection — the command looks at the first characters to decide EDIFACT vs X12. No --standard flag needed in most cases.
Two-phase parsing — Phase 1 always runs (raw segments). Phase 2 only runs if the user wants business objects AND a data package is installed.
Graceful fallback — if no data package is found, it warns and returns raw segments instead of crashing.

The Four Commands

# Parse: EDI file → JSON output
npx @ediflow/cli parse invoice.edi
npx @ediflow/cli parse invoice.edi --output-type business-object

# Validate: Check EDI against rules
npx @ediflow/cli validate invoice.edi

# Build: JSON → EDI string
npx @ediflow/cli build order.json --standard edifact --version d20b --message ORDERS

# Export Schema: Generate JSON Schema for a message type
npx @ediflow/cli export-schema --standard x12 --version 004010 --message 850

Each command is a class with register() and execute(). All injected via the DI Container.

Output Formatting — Supporting Multiple Formats

The CLI supports JSON and YAML output, with an option to strip empty values:

# Compact JSON (default)
npx @ediflow/cli parse invoice.edi

# Clean output — remove empty strings, null values, empty arrays
npx @ediflow/cli parse invoice.edi --skip-empty true

# Write to file
npx @ediflow/cli parse invoice.edi -o result.json

The OutputFormatter handles serialization and the --skip-empty flag recursively removes noise from the output — essential when dealing with EDI messages that have hundreds of optional fields.

How It All Connects — The Full Stack in One Call

When a user runs npx @ediflow/cli parse invoice.edi --output-type business-object, here's what happens:

CLI → ParseCommand
  → DIContainer.getInstance()
    → EdifactMessageParser (Infrastructure)
      → EdifactDelimiterDetector.detect()    ← reads UNA
      → EdifactTokenizer.tokenize()           ← splits segments
      → EdifactSegmentParser.parseSegment()   ← parses elements
    → ParseEDIUseCase.execute()              (Application)
      → IMessageParser.parse()               ← delegates to EDIFACT parser
      → StructureMappingService.map()         ← Phase 2: business object
    → FileBasedMessageStructureRepository    (Infrastructure)
      → loads ORDERS.json from data package
      → MessageStructureBuilder.build()
    → OutputFormatter.toJSON()               ← pretty-print result

Five layers. One call. No layer knows about the layers above or below it.

Lessons Learned

✅ Auto-detection makes the CLI feel smart — users don't need to specify the standard. The first 3 characters tell you if it's EDIFACT or X12.

✅ Graceful degradation — if a data package isn't installed, the CLI still works. It returns raw segments instead of business objects, with a helpful warning.

✅ Singleton DI Container is fine for CLI tools — no request scoping needed, no concurrent state. Simple is better.

✅ Commander.js for the CLI — no custom argument parsing. Commander handles flags, help text, and validation. We just define commands.

⚠️ The DI Container imports everything — this is intentional. It's the composition root. But it means the CLI package depends on all other packages. For a library this is fine — for a microservice architecture, you'd split differently.

What's Next — Part 6: Lessons Learned & The Road Ahead

The final part of the series. What worked? What didn't? What would we do differently? And where does EDIFlow go from here?

→ Part 1: Why Clean Architecture?
→ Part 2: Domain Layer
→ Part 3: Application Layer
→ GitHub: @ediflow/core

⭐ If this series helped you understand Clean Architecture in TypeScript — a star on GitHub keeps the project going: github.com/ediflow-lib/core

Do you use a DI container or plain constructor injection in your TypeScript projects? What's your experience? Drop a comment.

Building EDIFlow - Infrastructure Layer: Parsers, Repositories & Data Packages (Part 4)

hello-ediflow — Thu, 07 May 2026 03:44:18 +0000

Series: Building EDIFlow - A Clean Architecture Journey in TypeScript (Part 4/6)
Reading Time: ~12 minutes

Recap — Where We Left Off

In Part 3, we built the Application Layer — Use Cases, Output Ports (interfaces), DTOs, and the UseCaseFactory. Everything depends on abstractions, nothing on implementations.

Now it's time for the Infrastructure Layer — where theory meets reality. This is where IMessageParser becomes EdifactMessageParser, where IMessageStructureRepository becomes FileBasedMessageStructureRepository, and where 126–319 JSON message definitions get loaded at runtime.

┌───────────────────────────────────────────┐
│  🔥 INFRASTRUCTURE LAYER                  │  ← You are here
│  Parsers · Builders · Repositories        │
│                                           │
│  ┌─────────────────────────────────────┐  │
│  │      Application (Use Cases, Ports) │  │
│  │  ┌───────────────────────────────┐  │  │
│  │  │      Domain (Entities)        │  │  │
│  │  └───────────────────────────────┘  │  │
│  └─────────────────────────────────────┘  │
└───────────────────────────────────────────┘

Infrastructure in a Multi-Standard World — Why Three Packages?

In Clean Architecture, the Infrastructure Layer implements the interfaces defined by Domain and Application. But EDIFlow supports four standards (EDIFACT, X12, HIPAA, EANCOM) — so where does the infrastructure code live?

The answer: it's split across three infrastructure packages, each with a clear responsibility:

@ediflow/edifact              → EDIFACT-specific: parser, builder, validator, tokenizer
@ediflow/x12                  → X12-specific: parser, builder, delimiter detection
@ediflow/infrastructure-shared → Standard-agnostic: file loading, repositories, caching

Why not one big infrastructure package?

Because EDIFACT parsing and X12 parsing share zero implementation code. The delimiters are different (+:.' vs *~>), the envelope structure is different (UNB/UNZ vs ISA/GS/ST), the escape rules are different. Putting them together would create a God-package with no cohesion.

Why infrastructure-shared?

This package was primarily created for the CLI tool. The CLI needs to load message definitions for ALL standards — EDIFACT, X12, HIPAA, EANCOM — from a single entry point. The FileBasedMessageStructureRepository doesn't care whether the JSON describes an EDIFACT ORDERS or an X12 850. It can't live in @ediflow/edifact (X12 would depend on it) or @ediflow/x12 (vice versa). So it lives in a shared infrastructure package — mainly consumed by the CLI, but available to anyone who needs file-based data loading regardless of standard.

The dependency graph:

@ediflow/core  ←──  @ediflow/edifact
       ↑                    
       ├─────  @ediflow/x12
       ↑
       └─────  @ediflow/infrastructure-shared  ←──  @ediflow/cli

Every infrastructure package depends on core (for interfaces), never on each other. The CLI depends on all of them to wire everything together.

Now let's see what happens inside each package — starting with the parsing pipeline.

The Parsing Pipeline — Three Steps, Three Classes

Parsing an EDIFACT message isn't one operation — it's a pipeline:

Raw EDI String → Delimiter Detection → Tokenization → Segment Parsing → EDIMessage

Each step is a separate class implementing a separate interface. Here's why, and here's the real code.

Step 1: Delimiter Detection

EDIFACT messages can define custom delimiters via the UNA service string. The first 9 characters tell you which characters are used for components, elements, escaping, and segment termination:

export class EdifactDelimiterDetector implements IDelimiterDetector {
  private static readonly UNA_PREFIX = 'UNA';
  private static readonly UNA_LENGTH = 9;

  detect(message: string): Delimiters {
    if (this.hasUNA(message)) {
      return this.extractFromUNA(message);
    }
    // No UNA? Use EDIFACT defaults: + : . ? '
    return EdifactDelimiterDetector.DEFAULT_DELIMITERS;
  }

  private extractFromUNA(message: string): Delimiters {
    return Delimiters.custom({
      component: message.charAt(3),  // Usually ':'
      element:   message.charAt(4),  // Usually '+'
      decimal:   message.charAt(5),  // Usually '.'
      escape:    message.charAt(6),  // Usually '?'
      segment:   message.charAt(8),  // Usually "'"
    });
  }
}

This matters because real-world EDI partners sometimes use non-standard delimiters. Without this, your parser breaks on the first message from a partner who uses * instead of +.

Step 2: Tokenization

The tokenizer splits the raw string into segment strings, respecting escape characters:

export class EdifactTokenizer implements ITokenizer {
  tokenize(message: string, delimiters: Delimiters): string[] {
    const segments: string[] = [];
    let currentSegment = '';
    let position = 0;

    while (position < message.length) {
      const char = message[position];

      // Skip escaped characters (e.g., ?+ means literal +)
      if (this.isEscapedCharacter(message, position, delimiters)) {
        currentSegment += this.consumeEscapedCharacter(message, position);
        position += 2;
        continue;
      }

      // Segment terminator found — flush current segment
      if (char === delimiters.segment) {
        if (currentSegment.trim().length > 0) {
          segments.push(currentSegment);
        }
        currentSegment = '';
        position++;
        continue;
      }

      currentSegment += char;
      position++;
    }

    return segments;
  }
}

Why a separate class? Because X12 tokenization works differently — segments end with ~, and there's no escape character. Same interface (ITokenizer), completely different implementation.

Step 3: The Message Parser — Orchestrating the Pipeline

The EdifactMessageParser ties everything together:

export class EdifactMessageParser implements IMessageParser {
  constructor(
    private readonly delimiterDetector: IDelimiterDetector,
    private readonly tokenizer: ITokenizer,
    private readonly segmentParser: EdifactSegmentParser
  ) {}

  parse(ediString: string, config?: ParserConfig): EDIMessage {
    this.validateMessage(ediString);

    const delimiters = config?.delimiters || this.delimiterDetector.detect(ediString);
    const segmentStrings = this.tokenizer.tokenize(ediString, delimiters);
    const segments = segmentStrings.map(s => this.segmentParser.parseSegment(s, delimiters));

    const unhSegment = segments.find(s => s.tag === 'UNH');
    const { version, messageType } = this.extractMetadata(unhSegment!, delimiters);

    const message = EDIMessageFactory.create({
      standard: Standard.EDIFACT,
      version,
      messageType
    });

    segments.forEach(segment => message.addSegment(segment));
    return message;
  }

  canParse(ediString: string): boolean {
    return ediString.includes('UNH');
  }
}

Notice: the parser doesn't know tokenization internals. It delegates to ITokenizer and IDelimiterDetector. If we needed a streaming parser for huge messages, we'd swap the tokenizer — zero changes to the parser.

Building — The Reverse Pipeline

Building converts EDIMessage back to a raw string:

export class EdifactMessageBuilder implements IMessageBuilder {
  build(message: EDIMessage, options?: EdifactBuilderOptions): string {
    const delimiters = this.resolveDelimiters(options?.delimiters);
    const format = options?.format || OutputFormat.COMPACT;

    let result = '';
    if (options?.includeUNA) {
      result += delimiters.toUNA();  // "UNA:+.? '"
    }

    const segmentStrings = message.segments.map(seg =>
      this.serializeSegment(seg, delimiters)
    );

    return result + (format === OutputFormat.READABLE
      ? segmentStrings.join(delimiters.segment + '\n')
      : segmentStrings.join(delimiters.segment)) + delimiters.segment;
  }
}

Same interface IMessageBuilder — the X12 builder uses * and ~ instead.

Validation — Builder Pattern for Format-Specific Rules

Validation is composable. The builder lets you pick which rules to apply:

export class EdifactValidationServiceBuilder {
  private service = new ComposableValidationService<EDIMessage>();

  withBasicRules(): this {
    this.service.addRule(new MessageMustHaveSegmentsRule());
    this.service.addRule(new VersionStandardMustMatchRule());
    return this;
  }

  withEDIFACTRules(): this {
    this.service.addRule(new UNBMustBeFirstRule());
    this.service.addRule(new UNZMustBeLastRule());
    this.service.addRule(new EDIFACTSegmentTagFormatRule());
    return this;
  }

  withCustomRule(rule: IValidationRule<EDIMessage>): this {
    this.service.addRule(rule);
    return this;
  }

  // Factory shorthand
  static forEDIFACT(): ComposableValidationService<EDIMessage> {
    return new EdifactValidationServiceBuilder()
      .withBasicRules()
      .withEDIFACTRules()
      .build();
  }
}

Basic rules live in @ediflow/core (format-agnostic). EDIFACT rules live in @ediflow/edifact. X12 rules in @ediflow/x12. Each package only loads what it needs — tree-shaking friendly.

The Repository — Loading 126–319 Message Definitions at Runtime

This is where the data packages come in. Each package (@ediflow/edifact-d20b, @ediflow/x12-004010, ...) contains JSON files that define message structures:

packages/edifact-d20b/data/
  segments.json       # All segment definitions
  elements.json       # All element definitions
  composites.json     # Composite element definitions
  codes/              # Code list values
  messages/
    ORDERS.json       # ORDERS message structure
    INVOIC.json       # INVOIC structure
    DESADV.json       # ...195 message types total

The FileBasedMessageStructureRepository implements IMessageStructureRepository:

export class FileBasedMessageStructureRepository implements IMessageStructureRepository {
  private contextCache = new Map<string, DataPackageContext>();

  constructor(private readonly basePath: string) {}

  async getMessageStructure(standard: string, version: string, messageType: string): Promise<MessageStructureDTO | null> {
    const messageFile = await this.loadMessageFile(standard, version, messageType);
    if (!messageFile) return null;

    const { builder, validator } = await this.getOrCreateContext(standard, version);

    // Validate data package integrity
    const issues = validator.validate(messageFile);
    if (issues.length > 0) {
      throw new DataPackageValidationError(standard, version, messageType, issues);
    }

    return builder.build(messageFile);
  }
}

Key design decisions:

Lazy loading — segments, elements, composites are loaded on first access per version, then cached
Validation — every message file is validated against the data package (segment references, element references)
Package aliases — HIPAA maps to hipaa-x12-005010, EANCOM maps to eancom-2002
Qualifier fallback — HIPAA uses files like 837-Q1.json instead of 837.json

Monorepo Structure — Why 13 Packages?

packages/
  core/                   # Domain + Application (pure, no parsers)
  edifact/                # EDIFACT parser & builder
  x12/                    # X12 parser & validator
  infrastructure-shared/  # FileBasedRepository, loaders, caching
  cli/                    # CLI tool (4 commands)
  edifact-d96a/           # 126 EDIFACT D.96A message definitions
  edifact-d01b/           # EDIFACT D.01B definitions
  edifact-d12a/           # EDIFACT D.12A definitions
  edifact-d20b/           # 195 EDIFACT D.20B definitions
  eancom-2002/            # 50 GS1 retail messages
  x12-004010/             # 293 X12 transaction sets
  x12-006040/             # 319 X12 transaction sets
  hipaa-x12-005010/       # 14 HIPAA transaction sets

We already covered why the infrastructure is split into edifact, x12, and infrastructure-shared above. The data packages follow the same principle: install only what you need. A user working with X12 004010 shouldn't download 195 EDIFACT D.20B definitions. Each data package is independent — small, focused, and npm install on its own.

Lessons Learned

✅ Pipeline pattern for parsing — splitting into delimiter detection, tokenization, and segment parsing made each piece testable in isolation. When we added X12 support, we reused the pattern with different implementations.

✅ Data packages as separate npm packages — users install only what they need. Keeps bundle sizes small.

✅ Repository pattern with lazy loading — loading segments.json + elements.json + composites.json was expensive (~50ms). Caching per version eliminates this on subsequent calls.

✅ Builder pattern for validation — format-specific rules stay in format packages. Core remains agnostic. Adding HIPAA-specific rules? Create a new builder, compose with existing rules.

⚠️ Package aliases — HIPAA and EANCOM don't follow the {standard}-{version} naming convention. The alias map works but isn't elegant. Lesson: decide on naming conventions early.

What's Next — Part 5: Presentation Layer (CLI)

In Part 5, we'll see how the CLI ties everything together — the DI container that wires parsers + repositories + use cases, and how parse, validate, build, and export-schema commands work.

All already built and running in production. Part 5 walks through the real code.

→ Part 1: Why Clean Architecture?
→ Part 2: Domain Layer
→ Part 3: Application Layer
→ GitHub: @ediflow/core

⭐ If this series is useful — a star on GitHub helps others find it: github.com/ediflow-lib/core

How do you structure data packages in your monorepos? One giant package or many small ones? Drop a comment.

Building EDIFlow - Application Layer: Use Cases, Ports & Factories (Part 3)

hello-ediflow — Mon, 04 May 2026 08:51:55 +0000

Series: Building EDIFlow - A Clean Architecture Journey in TypeScript (Part 3/6)
Reading Time: ~10 minutes

Recap — Where We Left Off

In Part 2, we built the Domain Layer — the core entities (EDIMessage, EDISegment, EDIElement), value objects (Standard, Version, MessageType, Delimiters), and business rules.

Now it's time for the Application Layer — the part that orchestrates everything. It sits between your domain logic and the outside world:

┌─────────────────────────────────────────┐
│       Infrastructure (parsers, repos)   │
│                                         │
│  ┌───────────────────────────────────┐  │
│  │  🔥 APPLICATION LAYER             │  │  ← You are here
│  │  Use Cases · Services · Ports     │  │
│  │                                   │  │
│  │  ┌─────────────────────────────┐  │  │
│  │  │      Domain (entities)      │  │  │
│  │  └─────────────────────────────┘  │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

The golden rule: the Application Layer knows the Domain, but knows nothing about Infrastructure.

It talks to the outside world through Ports — interfaces that infrastructure must implement.

Ports — Only Output, No Input

In Clean Architecture, you'll often read about Input Ports (how the outside world calls you) and Output Ports (what you need from the outside world).

In EDIFlow, we only have Output Ports. Here's why:

Input Ports (Driving Ports) define how external actors invoke Use Cases. In EDIFlow, we currently have a CLI that calls Use Cases — and a REST API or web UI may come later. But we still don't need Input Port interfaces. Why? Because the DTO is the contract. Whether the CLI, a REST controller, or a React frontend invokes the Use Case, they all do the same thing: build a ParseEDIInputDTO and call useCase.execute(dto). A separate IParseEDIUseCase interface wouldn't add value — the method signature is identical regardless of who calls it.

And if that ever changes? Adding an Input Port interface is a 5-minute refactoring — extract an interface from the Use Case, done. The architecture supports it without any structural changes. We just don't add abstractions before they're needed.

Output Ports (Driven Ports) define what the Application Layer needs from Infrastructure — and that's where the real value is:

IMessageParser — "Give me something that can parse"

export interface IMessageParser {
  parse(ediString: string, config?: ParserConfig): EDIMessage;
  getSupportedStandard(): Standard;
  canParse(ediString: string): boolean;
  getConfiguration(): ParserConfig;
}

The Application Layer says: "I need something that can parse an EDI string and return an EDIMessage. I don't care if it's EDIFACT, X12, or anything else."

Implementations: EdifactMessageParser, X12MessageParser — both in the Infrastructure layer.

IMessageBuilder — "Give me something that can build"

export interface IMessageBuilder {
  build(message: EDIMessage, options?: MessageBuilderOptions): string;
  getSupportedStandard(): Standard;
}

Takes a domain EDIMessage, returns a raw EDI string. Format-agnostic — EDIFACT gets ' terminators, X12 gets ~.

IValidationService — "Give me something that can validate"

export interface IValidationService<T> {
  validate(entity: T, context?: ValidationContext): ValidationResult;
}

Generic — works with EDIMessage but could validate anything. Uses Strategy + Chain of Responsibility patterns: swap validators, chain them.

IMessageStructureRepository — "Give me message definitions"

export interface IMessageStructureRepository {
  getMessageStructure(standard: string, version: string, messageType: string): Promise<MessageStructureDTO | null>;
  getAllMessageTypes(standard: string, version: string): Promise<string[]>;
  hasMessageStructure(standard: string, version: string, messageType: string): Promise<boolean>;
  getCodeList(standard: string, version: string, codeListCode: string): Promise<Set<string> | null>;
}

This is the port that data packages (@ediflow/edifact-d20b, @ediflow/x12-004010, ...) implement. 126–319 JSON definitions per package, loaded at runtime through this single interface.

Why only Output Ports?

	Input Port (Driving)	Output Port (Driven)
Direction	Outside → Application	Application → Infrastructure
EDIFlow	❌ Not needed — DTO is the contract, CLI/API/UI all call `execute(dto)`	✅ All infrastructure contracts
Benefit	Useful when entry points need different method signatures	Essential — decouples Application from Infrastructure

The rule of thumb: if every caller uses the same execute(dto) method, you don't need an Input Port — the DTO is your contract.

Why this matters for EDIFlow: The EDIFACT parser, the X12 parser, the HIPAA validator — they all implement these same Output Port interfaces. The Application Layer doesn't know any of them exist. When we added X12 support months after EDIFACT, zero code changed in the Application Layer.

Use Cases — One Class, One User Intention

A Use Case represents one thing a user wants to do. Not more. In EDIFlow we have three:

Use Case	User Intention
`ParseEDIUseCase`	"I want to parse this EDI string"
`ValidateMessageUseCase`	"I want to validate this message"
`BuildEDIUseCase`	"I want to build an EDI string from data"

ParseEDIUseCase — The Real Code

Here's what actually runs when you call service.parse():

export class ParseEDIUseCase {
  constructor(
    private readonly messageParser: IMessageParser,
    private readonly structureMappingService?: StructureMappingService
  ) {}

  execute(input: ParseEDIInputDTO): ParseEDIOutputDTO {
    try {
      // Guard: empty input
      if (!input.message || input.message.trim().length === 0) {
        return this.createErrorResult(input, {
          code: 'EMPTY_MESSAGE',
          message: 'Message cannot be empty',
        });
      }

      // Guard: parser compatibility
      if (!this.messageParser.canParse(input.message)) {
        return this.createErrorResult(input, {
          code: 'UNSUPPORTED_FORMAT',
          message: 'Parser does not support this message format',
        });
      }

      // Phase 1: EDI String → EDIMessage
      const message = this.messageParser.parse(input.message, input.parserConfig);

      // Phase 2: EDIMessage → Business Object (optional)
      let businessObject: unknown;
      if (input.returnTypedObject && input.messageStructure && this.structureMappingService) {
        businessObject = this.structureMappingService.map(message, input.messageStructure);
      }

      return {
        success: true,
        message,
        businessObject,
        metadata: {
          standard: message.standard,
          version: message.version,
          messageType: message.messageType,
          segmentCount: message.segments.length,
        },
      };
    } catch (error) {
      return this.createErrorResult(input, {
        code: 'PARSE_ERROR',
        message: error instanceof Error ? error.message : 'Unknown error',
      });
    }
  }
}

Notice the pattern:

Validate input — fail fast
Delegate to port — this.messageParser.parse()
Optionally enrich — Phase 2 mapping
Return a DTO — never expose domain internals directly

No framework. No decorators. No magic. Just TypeScript classes with constructor injection.

ValidateMessageUseCase — Composing Validation Phases

Validation is more complex — it runs in three phases, each building on the previous:

export class ValidateMessageUseCase {
  constructor(private readonly validationService: IValidationService<EDIMessage>) {}

  execute(input: ValidateMessageInputDTO): ValidateMessageOutputDTO {
    // Phase 1: Syntax validation
    const syntaxResult = this.validationService.validate(input.message);

    // Phase 2: Structure validation (segments in correct order?)
    const structureResult = this.performStructuralValidation(input, syntaxResult);

    // Phase 3: Code list validation (valid code values?)
    const finalResult = this.performCodeValidation(input, structureResult);

    return this.buildSuccessResponse(input.message, finalResult);
  }
}

The interesting part: in strict mode, Phase 2 only runs if Phase 1 passed. Phase 3 only runs if Phase 2 passed. This prevents cascading error messages that confuse users.

BuildEDIUseCase — From Business Object to EDI

Building works in reverse — you provide either an EDIMessage directly, or a business object that gets unmapped:

export class BuildEDIUseCase {
  constructor(
    private readonly messageBuilder: IMessageBuilder,
    private readonly envelopeBuilder?: IEnvelopeBuilder,
    private readonly structureMappingService?: StructureMappingService
  ) {}

  execute(input: BuildEDIInputDTO): BuildEDIOutputDTO {
    // Get message from either direct input or business object unmap
    let message = this.getMessageFromInput(input);

    // Optionally wrap with envelope (UNB/UNH for EDIFACT, ISA/GS for X12)
    if (input.includeEnvelope) {
      message = this.wrapWithEnvelope(message, input);
    }

    // Optionally validate before building
    if (input.validateBeforeBuild) {
      const error = this.validateMessage(message);
      if (error) return error;
    }

    // Build the EDI string
    const ediString = this.messageBuilder.build(message, {
      delimiters: input.delimiters,
      format: input.format || OutputFormat.COMPACT
    });

    return { success: true, ediString };
  }
}

This is the round-trip feature: parse() converts EDI → JSON, build() converts JSON → EDI. Same message structure definition drives both directions.

DTOs — Type-Safe Input/Output

Every Use Case has a Request (Input) and a Response (Output) DTO. No domain objects leak out:

export interface ParseEDIInputDTO {
  message: string;
  standard: Standard;
  strictMode?: boolean;
  parserConfig?: ParserConfig;
  returnTypedObject?: boolean;
  messageStructure?: MessageStructureDTO;
  mappingKeyStrategy?: MappingKeyStrategy;
}

And the output uses a discriminated union — TypeScript narrows the type based on success:

export type ParseEDIOutputDTO =
  | {
      success: true;
      message: EDIMessage;
      businessObject?: unknown;
      metadata: { standard: Standard; version: Version; messageType: MessageType; segmentCount: number; };
    }
  | {
      success: false;
      errors: ParseError[];
      metadata: { standard: Standard; segmentCount: number; };
    };

When you check result.success === true, TypeScript knows result.message exists. When it's false, TypeScript knows result.errors exists. No runtime checks needed.

The Factory — Wiring Without a Framework

How do Use Cases get their dependencies? Through a Factory:

export class UseCaseFactory {
  constructor(
    private readonly parsers: Map<string, IMessageParser>,
    private readonly builders: Map<string, IMessageBuilder>,
    private readonly validationService: IValidationService<EDIMessage>
  ) {}

  createParseUseCase(standard: string, mapper?: StructureMappingService): ParseEDIUseCase {
    const parser = this.parsers.get(standard.toUpperCase());
    if (!parser) {
      throw new Error(`No parser registered for standard: ${standard}`);
    }
    return new ParseEDIUseCase(parser, mapper);
  }

  createBuildUseCase(standard: string, mapper?: StructureMappingService): BuildEDIUseCase {
    const builder = this.builders.get(standard.toUpperCase());
    if (!builder) {
      throw new Error(`No builder registered for standard: ${standard}`);
    }
    return new BuildEDIUseCase(builder, undefined, mapper);
  }

  createValidateUseCase(): ValidateMessageUseCase {
    return new ValidateMessageUseCase(this.validationService);
  }
}

No DI container. No @Injectable(). Just a Map of implementations and a factory method. Simple, testable, no framework coupling.

Testing a Use Case — Easy When Dependencies Are Interfaces

Because Use Cases depend only on interfaces, testing is trivial:

import { describe, it, expect, vi } from 'vitest';
import { ParseEDIUseCase } from './ParseEDIUseCase';
import { Standard } from '@domain';

describe('ParseEDIUseCase', () => {
  it('returns error for empty message', () => {
    const mockParser = { canParse: vi.fn(), parse: vi.fn(), /* ... */ };
    const useCase = new ParseEDIUseCase(mockParser);

    const result = useCase.execute({
      message: '',
      standard: Standard.EDIFACT,
    });

    expect(result.success).toBe(false);
    expect(result.errors![0].code).toBe('EMPTY_MESSAGE');
  });

  it('delegates to parser and returns structured result', () => {
    const mockMessage = { standard: Standard.EDIFACT, segments: [], /* ... */ };
    const mockParser = {
      canParse: vi.fn().mockReturnValue(true),
      parse: vi.fn().mockReturnValue(mockMessage),
      getConfiguration: vi.fn().mockReturnValue({ delimiters: {} }),
    };

    const useCase = new ParseEDIUseCase(mockParser);
    const result = useCase.execute({
      message: "UNH+1+ORDERS:D:96A:UN'",
      standard: Standard.EDIFACT,
    });

    expect(result.success).toBe(true);
    expect(mockParser.parse).toHaveBeenCalledOnce();
  });
});

No HTTP server to spin up. No database. No parsers. Just a mock that implements the interface.

Lessons Learned

After building this layer, here's what I'd do the same again — and what I'd change:

✅ Keep Use Cases stupid simple — they validate input, call a port, return a DTO. If a Use Case is complex, logic belongs in a Domain Service or the Use Case is doing too much.

✅ Discriminated unions for output DTOs — TypeScript's type narrowing eliminates an entire class of null-check bugs.

✅ Ports (interfaces) first — define what you need before building what provides it. The EDIFACT parser and X12 parser were built months apart, both implementing the same IMessageParser. Zero changes to the Application Layer.

✅ Optional dependencies work fine — StructureMappingService as optional constructor parameter is genuinely optional functionality (Phase 2 mapping). Not every user needs business object mapping. Keeping it optional in the same Use Case avoids creating a second ParseToBusinessObjectUseCase that would duplicate the entire parsing pipeline. Sometimes a simple ? is the right call.

What's Next — Part 4: Infrastructure Layer

In the next part, we'll show how the interfaces we defined here get implemented — the EDIFACT tokenizer, X12 envelope parser, file-based repositories, and how data packages with 126–319 message definitions per package are loaded at runtime.

All of this is already built and running in production. Part 4 will walk through the real implementation code.

This is where the architecture pays off: the EDIFACT parser and the X12 parser were built months apart — both implementing the same IMessageParser interface. Zero changes needed in the Application Layer.

→ Part 1: Why Clean Architecture?
→ Part 2: Domain Layer
→ GitHub: @ediflow/core

⭐ If this series is useful — a star on GitHub helps others find it: github.com/ediflow-lib/core

What patterns do you use in your Application Layer? Controllers? Mediators? Interactors? I'd love to hear — drop a comment.

EDIFlow v0.3.0: X12, HIPAA & EANCOM Support for TypeScript — The Way of Water

hello-ediflow — Mon, 04 May 2026 05:23:18 +0000

"Water doesn't fight obstacles. It flows." — Lao Tzu

EDI data should move through systems naturally — adapting to any standard, connecting everything, never fighting complexity. That's the philosophy behind EDIFlow. And v0.3.0 is the biggest step yet.

What is EDIFlow?

EDIFlow is an open-source TypeScript library for parsing, validating and building EDI messages — type-safe, zero-config, built with Clean Architecture.

If you've ever dealt with raw EDI like this:

ISA*00*          *00*          *ZZ*SENDER         *ZZ*RECEIVER       *260101*1200*^*00401*000000001*0*T*:~
GS*PO*SENDER*RECEIVER*20260101*1200*1*X*004010~
ST*850*0001~
BEG*00*SA*ORDER12345**20260101~

...and wished there was a modern, type-safe TypeScript API to work with it — that's exactly what EDIFlow solves.

v0.3.0 — What's new

🔷 X12 — Two full versions

X12 is the dominant EDI standard in North America — used in retail, logistics, healthcare, finance.

v0.3.0 ships two complete X12 version packages:

Package	Version	Transaction Sets
`@ediflow/x12-004010`	X12 004010	293 transaction sets
`@ediflow/x12-006040`	X12 006040	319 transaction sets

850 (Purchase Order), 810 (Invoice), 856 (Ship Notice), 837 (Healthcare Claim), 835 (Remittance), 997 (Acknowledgment), 214, 204, 210 and hundreds more.

import { X12ServiceBuilder } from '@ediflow/x12';
import { x12_004010Repository } from '@ediflow/x12-004010';

const service = new X12ServiceBuilder()
  .withRepository(x12_004010Repository)
  .build();

const result = await service.parse(rawX12String);
// Fully typed — TypeScript knows the structure
console.log(result.message.segments[0].tag); // 'ISA'

Switch to 006040 by swapping one import — no other code changes needed.

🏥 HIPAA X12 005010 — Healthcare EDI

14 HIPAA-specific transaction sets out of the box:

837P — Professional Claim
837I — Institutional Claim
835 — Remittance Advice
270/271 — Eligibility Inquiry & Response
276/277 — Claim Status
834 — Benefit Enrollment
820 — Payment Order

npm install @ediflow/core @ediflow/x12 @ediflow/hipaa-x12-005010

🌍 EDIFACT — Full coverage across 4 versions

EDIFACT is the international standard — dominant in Europe, logistics, supply chain.

All four versions are supported with complete message sets:

Package	Version	Messages
`@ediflow/edifact-d96a`	D.96A	126 message types
`@ediflow/edifact-d01b`	D.01B	full standard
`@ediflow/edifact-d12a`	D.12A	full standard
`@ediflow/edifact-d20b`	D.20B	195 message types

Every message type in the standard — ORDERS, INVOIC, DESADV, RECADV, SLSRPT, PRICAT, REMADV, IFTMIN, COPARN, APERAK, CONTRL, and hundreds more — available out of the box. No custom definitions needed.

npm install @ediflow/core @ediflow/edifact @ediflow/edifact-d20b

🛒 EANCOM 2002 — GS1 Retail Standard

50 GS1 retail message types built on EDIFACT syntax. Covers the complete retail supply chain with full GS1 GLN party identification and EAN-13/GTIN product codes:

ORDERS, ORDRSP, DESADV, RECADV, INVOIC, REMADV, SLSRPT, PRICAT, INVRPT, PRODAT and more.

npm install @ediflow/core @ediflow/edifact @ediflow/eancom-2002

🔄 Business Object Mapping — Round-Trip

This is the feature I'm most excited about. Instead of manually navigating segment arrays, you map EDI messages directly to/from typed JSON objects:

import { StructureMappingService } from '@ediflow/core';

const mappingService = new StructureMappingService();

// EDI → Business Object (JSON)
const order = mappingService.map(parsedMessage);
console.log(order['BGM']['1004']); // "ORDER12345" — document number

// Modify the business object
order['BGM']['1004'] = 'ORDER99999';

// Business Object → EDI (rebuild round-trip)
const rebuilt = mappingService.unmap(order);

Five key strategies for property names: code, name, camelCase, snake_case, kebab-case — choose what fits your codebase.

⚙️ CLI enhancements

The @ediflow/cli package now supports business object output and schema export for both EDIFACT and X12:

# Parse to business object
npx @ediflow/cli parse invoice.edi --output-type business-object

# Export full JSON schema for a message type
npx @ediflow/cli export-schema --standard x12 --version 004010 --message 850

# Build EDI from a JSON business object
npx @ediflow/cli build order.json --standard edifact --version d20b --message ORDERS

📂 Ready-to-run examples

Clone the repo and run any example with npx tsx:

git clone https://github.com/ediflow-lib/core.git
npm install

# X12
npx tsx examples/x12/parse-850/index.ts        # Parse Purchase Order
npx tsx examples/x12/build-850/index.ts        # Build 850 + round-trip
npx tsx examples/x12/validate-837/index.ts     # Validate Healthcare Claim
npx tsx examples/x12/multi-message/index.ts    # Parse 850 + 810 + 856 + 997

# EDIFACT
npx tsx examples/edifact/parse-orders/index.ts    # Parse ORDERS
npx tsx examples/edifact/build-invoic/index.ts    # Build INVOIC + round-trip

# HIPAA
npx tsx examples/hipaa/parse-837/index.ts     # Parse 837P Professional Claim

# EANCOM
npx tsx examples/eancom/parse-desadv/index.ts # Parse DESADV (GLN + EAN-13)

All examples include real EDI sample data and commented output — no setup beyond npm install.

By the numbers

📦 13 packages on NPM
🔷 X12: 293 + 319 transaction sets across 2 versions
🌍 EDIFACT: 126 + 195 message types across 4 versions
🛒 EANCOM: 50 GS1 retail messages
🏥 HIPAA: 14 transaction sets
✅ 711 tests passing
📊 ≥ 90% code coverage (@ediflow/core)
0 TypeScript errors, 0 warnings
⚖️ MIT License

Install

# X12 004010 (293 transaction sets)
npm install @ediflow/core @ediflow/x12 @ediflow/x12-004010

# X12 006040 (319 transaction sets)
npm install @ediflow/core @ediflow/x12 @ediflow/x12-006040

# EDIFACT D.20B (195 messages)
npm install @ediflow/core @ediflow/edifact @ediflow/edifact-d20b

# HIPAA
npm install @ediflow/core @ediflow/x12 @ediflow/hipaa-x12-005010

# EANCOM 2002
npm install @ediflow/core @ediflow/edifact @ediflow/eancom-2002

→ Full changelog
→ Examples
→ Quick Start

The Way of Water 🌊

I've been building EDIFlow alone — no team, no funding. Just a belief that TypeScript developers working in supply chain, logistics, and healthcare deserve better EDI tooling than what exists today.

The name isn't accidental. Inspired by the Taoist "Way of Water": EDI data should move through systems naturally — adapting to any standard, connecting everything, never forcing complexity on the developer.

💧 Finds its way — intelligent parsing, adaptive error handling
🌊 Adapts to any form — EDIFACT, X12, HIPAA, EANCOM, more coming
💪 Powerful but gentle — enterprise-grade performance, clean API
🔄 Connects everything — one unified interface for all EDI standards

If this resonates — or if you're tired of fighting brittle EDI parsers — consider giving the project a ⭐ on GitHub. It helps others find it.

⭐ Star EDIFlow on GitHub

What EDI standard are you working with? Drop a comment — I'd love to know what matters most for the next release.

Building EDIFlow in TypeScript: Part 2 - Domain Layer Deep-Dive

hello-ediflow — Tue, 10 Feb 2026 11:08:44 +0000

Series: Building EDIFlow - A Clean Architecture Journey in TypeScript (Part 2/6)

Author: EDIFlow

Published: February 2026

Reading Time: ~10-12 minutes

Welcome Back! 👋

In Part 1, I shared why I built EDIFlow and why Clean Architecture was the right choice.

Now it’s time for the hard part: design decisions.

Today we focus on the Domain Layer — not the implementation details, but the decisions that shaped it.

What you’ll learn:

What objects to model (and what NOT to model)
Decision criteria for Entity vs Value Object
Trade-offs that influenced the design
Why DDD + Clean Architecture belong together
What you can reuse in your own systems

No perfect solutions — just real decisions with real trade-offs.

1. The First Question: What IS the Domain? 🤔

This sounds obvious, but it’s the hardest question in Clean Architecture:

“What belongs in the Domain Layer?”

Uncle Bob says in Clean Architecture:

“The Domain Layer contains Enterprise Business Rules. These are the rules that would exist even if the application didn't exist.”

Translation: Domain = pure business logic, independent of technology.

My Challenge with EDIFlow

EDIFlow parses messages. But what’s the “domain”?

First instinct (wrong):

Domain = Parsing logic

❌ Parsing is technical, not business.

I spent a week building parsers in the domain layer. Big mistake! When I tried to add X12 support, I had to change the domain. That's when I realized: if adding a new format changes your domain, your domain is wrong.

Second try:

Domain = Message structure (segments, elements)

⚠️ Better, but still technical.

Final answer:

Domain = Business concepts that exist independently
- A message has a type
- A message has a version
- A message has validation rules
- A message has identity

✅ This is the domain. It exists before parsing, after parsing, and independent of any parser.

Key lesson: Don't confuse technical implementation with business concepts. I learned this the hard way!

2. Enter Domain-Driven Design 📚

Now I knew what belongs in the Domain Layer. But I still had a problem: Which objects do I create?

Clean Architecture tells me where logic belongs. It doesn’t tell me how to model that logic.

That’s where Domain-Driven Design (DDD) helps. Eric Evans describes several building blocks for domain modeling:

Entities - Objects with identity
Value Objects - Objects defined by value
Aggregates - Cluster of entities with a root
Domain Services - Operations that don’t belong to objects
Repositories - Persistence abstractions
Factories - Complex object creation

Note: These ideas existed before DDD, but Evans made them clear and practical for domain modeling.

3. Why DDD + Clean Architecture? 🔗

Why do I need both? Because they solve different problems:

	Domain-Driven Design	Clean Architecture
Answers	WHAT to model	HOW to structure
Question	What objects? What relationships?	Where does code go?
Gives you	Entities, Value Objects, Aggregates	Layers, Dependencies, Boundaries
Goal	Model business correctly	Structure code maintainably

Together they’re powerful:

DDD tells you WHAT:
- EDIMessage is an Entity (identity)
- Version is a Value Object (value-based)
- Standard is an Enum (type-safe set)

Clean Architecture tells you WHERE:
- Entities live in Domain Layer
- Parsers live in Infrastructure Layer
- Use Cases live in Application Layer

Real example (compact):

DDD Decision:
"Version is a Value Object" (immutable, no identity)

Clean Architecture Decision:
"Version lives in domain/value-objects/ with zero dependencies"

Result:
✅ Correct model (DDD)
✅ Correct structure (Clean Architecture)
✅ Portable + testable

Both complement each other: DDD without structure = mess. Structure without domain insight = technical code without business value.

4. Why Focus Only on Entities & Value Objects? 🎯

DDD has many building blocks, but this article focuses on just two:

Entities - objects with identity
Value Objects - objects defined by value

Why only these two?

Honest answer: Because EDIFlow’s Domain Layer is simple:

✅ No Aggregates (EDIMessage is simple enough)
✅ No Domain Services (operations fit in objects or use cases)
✅ No Repositories in Domain (they belong in Infrastructure)
✅ No Factories needed (constructors are enough)

YAGNI applies here. Don’t add patterns you don’t need.

Later parts in the series:

Part 3: Use Cases, Services, DTOs
Part 4: Repositories, Parsers

5. The Big Decision: Entity or Value Object? 📦

I use a simple decision matrix:

Question	If YES →	If NO →
Does it have an ID?	Entity	Value Object
Can two be equal with different values?	Entity	Value Object
Does it change over time?	Entity	Value Object
Do I need to track its history?	Entity	Value Object

Applied to all EDIFlow domain objects:

Object	Has ID?	Equal w/ diff values?	Changes?	Track history?	Verdict
EDIMessage	✅	✅	❌	✅	Entity
Version	❌	❌	❌	❌	Value Object
MessageType	❌	❌	❌	❌	Value Object
Delimiters	❌	❌	❌	❌	Value Object
Standard	❌	❌	❌	❌	Value Object (Enum)
EDISegment	❌	❌	❌	❌	Value Object
EDIElement	❌	❌	❌	❌	Value Object

Pattern: Only EDIMessage has identity. Everything else is a Value Object.

Key insight (1:6 ratio):

1 Entity (EDIMessage)
6 Value Objects (everything else)

DDD takeaway: Start by assuming Value Object. Only choose Entity if identity truly matters.

See It In Action

Here's how the decision matrix plays out in real code:

// Entity: Has identity, can be equal despite different values
const message1 = new EDIMessage('ORDER-001', version, type, segments);
const message2 = new EDIMessage('ORDER-001', version, type, segments);
message1.equals(message2); // ✅ true (same ID!)

// Value Object: No identity, equals by value only
const v1 = new Version(Standard.EDIFACT, 'D.96A');
const v2 = new Version(Standard.EDIFACT, 'D.96A');
v1.equals(v2); // ✅ true (same value!)

const v3 = new Version(Standard.EDIFACT, 'D.01B');
v1.equals(v3); // ❌ false (different value!)

Why this matters: Two orders with same content are different orders (Entity). Two versions "D.96A" are the same version (Value Object).

6. The Hardest Decision: Polymorphism vs Simplicity 🎭

EDIFlow supports multiple formats (EDIFACT, X12, IDOC). Each has different rules.

How do I model this?

I struggled with this for days. Every approach felt wrong:

Separate classes = duplication
if/else = messy
Polymorphism = complex?

Let me show you the three options I considered:

Option 1: Separate Classes (Naive)

class EdifactVersion {}
class X12Version {}
class IdocVersion {}

Pros: Simple, clear

Cons: Duplication, hard to extend

❌ Rejected (violates DRY)

Option 2: if/else Everywhere

if (standard === 'EDIFACT') { ... }

Pros: One class

Cons: Breaks OCP, hard to test

❌ Rejected

Option 3: Polymorphic Value Object (Chosen)

class Version {
  private static PATTERNS = { EDIFACT: /.../, X12: /.../ };
}

Pros: One class, extensible, type-safe

Cons: Slightly more complex

✅ Chosen (best trade-off)

7. Trade-Off Example: Validation Strategy 📊

Approach	Pros	Cons	Chosen?
External Validator	Flexible	Separate logic	❌
Self-validating constructor	Fail-fast	Exceptions	✅
Factory method	Controlled	Extra layer	⚠️

Why self-validation: It makes invalid state impossible.

8. What I'd Do Differently 🤔

Let me be honest about mistakes and second thoughts:

Mistake #1: Almost Over-Engineered Version

What I almost did:

interface IVersion { ... }
class EdifactVersion implements IVersion { }
class X12Version implements IVersion { }

Why I didn't: YAGNI! The polymorphic approach works great. Don't create interfaces until you need them.

Lesson: Resist the urge to make everything "extensible." Simple solutions often stay simple.

Mistake #2: First Draft Had 50+ Classes

My very first attempt had separate classes for everything:

EdifactDelimiters, X12Delimiters
EdifactSegment, X12Segment
EdifactElement, X12Element

Why that was bad: Massive duplication. 80% of the code was identical.

What I learned: Look for patterns before creating classes. Most Value Objects are format-agnostic.

Thought #1: Should I Use Result Types?

Right now, constructors throw exceptions:

new Version(Standard.EDIFACT, 'INVALID'); // throws!

Alternative: Result types (functional style):

Version.create('INVALID'); // returns Result<Version, Error>

Why I didn't: Most TypeScript developers expect exceptions. Result types are great, but add learning curve.

Would I change it? Maybe in v2.0 with a Version.tryCreate() method. For now, exceptions work fine.

9. What You Get From This Design 🎁

✅ Type safety (less guessing)
✅ Invalid state impossible
✅ Clear separation of concerns
✅ Easier testing (pure logic)
✅ No breaking changes when adding formats

10. What's Next? 🚀

Part 3: Application Layer

Use Cases
Services
DTOs
Dependency Injection (no framework)

11. Conclusion 🎯

Domain design is about decisions:

What to model
How to classify objects
What trade-offs to accept

EDIFlow’s Domain Model:

1 Entity: EDIMessage
6 Value Objects: Standard, Version, MessageType, Delimiters, EDISegment, EDIElement

Rule of thumb: Start with Value Object. Promote to Entity only when identity truly matters.

📚 Series Navigation

Part 1 (Published):

Part 1: Why Clean Architecture?

Upcoming Parts:

Part 3: Application Layer - Use Cases & Services
Part 4: Infrastructure Layer & Monorepo
Part 5: Presentation Layer - CLI
Part 6: Lessons Learned & The Big Refactoring

💬 Let’s Discuss

How do you decide between Entity and Value Object in your projects?

Do you prefer decision matrices like this?
What trade-offs do you value most (simplicity, extensibility, strictness)?
Have you used DDD + Clean Architecture together?

I’d love to hear your approach — drop your thoughts in the comments.

🔗 Links & Resources

EDIFlow:

Community:

💬 Discord: EDIFlow Community
📣 GitHub Discussions

Books:

📚 Clean Architecture by Robert C. Martin
📚 Domain-Driven Design by Eric Evans
📚 Clean Code by Robert C. Martin

Part 3 is next: Application Layer.

Building EDIFlow in TypeScript: Part 1 - Why Clean Architecture?

hello-ediflow — Tue, 03 Feb 2026 06:14:36 +0000

Series: Building EDIFlow - A Clean Architecture Journey in TypeScript (Part 1/6)

Author: EDIFlow

Published: February 2026

Reading Time: ~7 minutes

1. Introduction - The Problem 🤔

I've been working in data integration for over 20 years. SOAP, REST APIs, and yes—EDI. Lots of EDI.

If you've ever worked with EDIFACT, you know the pain:

UNH+1+ORDERS:D:96A:UN'
BGM+220+ORDER12345+9'
DTM+137:20240201:102'
NAD+BY+BUYER123::92'

What does BGM+220 mean? What is DTM+137? What's ::92?

This is the "old school EDI" world:

❌ No human-readable names
❌ Just codes and tags (BGM, NAD, DTM...)
❌ Makes onboarding new developers incredibly hard

And the existing parsers? They don't help much:

// ❌ Typical EDI Parser - Generic segments
const bgm = message.segments.find(s => s.tag === 'BGM');
const docNumber = bgm?.elements[1]?.value;  // What is element[1]? 🤷

No type safety. No IntelliSense. No business logic.

After 20+ years of this, I had enough. I wanted to build an EDI library that:

✅ Maps to type-safe TypeScript business objects
✅ Uses Clean Architecture principles
✅ Makes EDI development enjoyable (yes, really!)

So I started EDIFlow.

But here's the honest truth: I didn't just want to build a library. I wanted to LEARN Clean Architecture by doing.

2. Why Clean Architecture? 📚

The Honest Answer: I Wanted to Learn It!

I first encountered Clean Architecture around 2020. Read the books:

I was hooked. The principles made so much sense:

Single Responsibility
Dependency Inversion
Separation of Concerns
Testability

But then I tried to apply it at work...

The Reality: Resistance to Change

Typical problems I faced:

🏢 "We've always done it this way"
😰 "New architecture? Too risky!"
⏰ "We don't have time to refactor"
🤷 "Why change if it works?"

The structures were too entrenched. No trust in "new" architectures. The typical corporate fears.

Sound familiar?

The Solution: Build My Own Project

I realized: The best way to learn Clean Architecture is to build something real from scratch.

Not a TODO app. Not a toy example. A real-world library that solves a real problem.

So when I decided to build EDIFlow, I made a commitment:

✅ Clean Architecture from Day 1
✅ TDD (Test-Driven Development)
✅ Agile principles (even solo!)
✅ No compromises on code quality

Could I have hacked it together in a weekend? Sure!

But where's the learning in that? 🤷

So... Was Clean Architecture Worth It?

This is the question everyone asks: "Is Clean Architecture worth the extra effort?"

My answer: YES! But it wasn't without challenges.

What went well:

✅ 599 tests - Writing tests became easy (and fun!)
✅ Zero coupling - Changed parser implementation twice, no problem
✅ Added 4 EDIFACT versions - Clean separation made it trivial
✅ Confidence - I can refactor without fear

But there were challenges too:

⚠️ More files - Sometimes felt like overkill for simple features
⚠️ Initial velocity - First weeks were slower ("I could have hacked this in a weekend!")
⚠️ TypeScript DI complexity - No framework = manual wiring gets verbose
⚠️ Solo discipline - Easy to cut corners when no one is watching

The verdict? For a library like EDIFlow: Absolutely worth it! Every hour spent on architecture saved me days in maintenance.

For a throwaway script? Probably overkill.

(We'll dive into the honest pros & cons, with real examples, in Part 5!)

3. Why TypeScript? 💙

EDI parsing is complex. You're dealing with:

618+ message types (ORDERS, INVOIC, DESADV...)
Thousands of segment definitions
Complex validation rules
Delimiters, escape characters, special cases

Without type safety, this becomes a nightmare.

TypeScript Benefits for EDIFlow:

1. Type Safety for Complex Parsing Logic

// ❌ JavaScript - Runtime errors waiting to happen
const delimiters = {
  component: ':',
  element: '+',
  segment: "'"
};
delimiters.component = delimiters.element; // Oops! No error! 💥

// ✅ TypeScript - Caught at compile time
export class Delimiters {
  private constructor(
    public readonly component: string,
    public readonly element: string,
    public readonly segment: string
  ) {
    if (component === element) {
      throw new Error("Delimiters must be different!");
    }
  }
}

2. IntelliSense = Developer Happiness

// ✅ Auto-completion works!
const order = mapper.mapToBusinessObject(message);
console.log(order.documentNumber);        // IntelliSense suggests fields
console.log(order.parties.buyer.id);      // Type-safe navigation
console.log(order.lineItems[0].quantity); // No guessing!

3. Interface-Driven Design (Perfect for Clean Architecture!)

// Domain Layer - Just an interface, no implementation details
export interface IEDIParser {
  parse(message: string): EDIMessage;
}

// Infrastructure Layer - Implements the interface
export class EdifactMessageParser implements IEDIParser {
  parse(message: string): EDIMessage {
    // EDIFACT-specific logic here
  }
}

This is Dependency Inversion in action! The domain doesn't know about EDIFACT. The domain just knows "I need a parser."

4. Easy to Publish to npm

TypeScript compiles to JavaScript, so it works everywhere:

npm install @ediflow/core     # Works in Node.js
import { EdifactParser } from '@ediflow/core';  # Works in browsers (with bundler)

Plus, TypeScript generates .d.ts files automatically—users get IntelliSense out of the box!

5. Strong Ecosystem

Vitest for testing (fast, great DX)
tsup for building (zero config!)
TypeScript strict mode catches bugs early

TypeScript Made EDI Development Enjoyable

Before EDIFlow, EDI development was:

😫 Debugging runtime errors
🤷 Guessing what element[3] means
💥 Breaking changes at runtime

With TypeScript:

✅ Compile-time safety
✅ IntelliSense everywhere
✅ Refactoring with confidence

TypeScript isn't just a nice-to-have for EDIFlow. It's essential.

4. Why Open Source? 🌍

Learning in Public

I could have built EDIFlow as a private project. But I chose open source for several reasons:

1. Accountability

When you know others might read your code, you write better code.

No shortcuts. No "I'll fix this later." Everything has to be production-ready.

2. Community Feedback

Open source means:

🐛 Bug reports from real users
💡 Feature suggestions I never thought of
🤝 Potential contributors
📖 Documentation improvements

The best products are built WITH the community, not just FOR them.

3. Portfolio & Learning

Let's be honest: If I'm spending 100+ hours building this, I want to:

✅ Show it in my portfolio
✅ Get feedback from experts
✅ Help others with the same problem
✅ Build my personal brand

Open source is the ultimate resume.

4. Solving a Real Problem

I'm not the only one struggling with EDI libraries. By open-sourcing EDIFlow, I hope to:

Help developers new to EDI
Provide a modern alternative to legacy tools
Show that EDI can be developer-friendly

5. MIT License = Maximum Freedom

EDIFlow is MIT licensed:

✅ Use it commercially
✅ Modify it however you want
✅ No attribution required (but appreciated!)
✅ No strings attached

Why MIT? Because I want maximum adoption. The more people use it, the better it gets.

5. What is EDIFlow? 🚀

Okay, enough about motivation. What IS EDIFlow?

EDI = Electronic Data Interchange

Companies exchange business documents electronically:

Purchase Orders (ORDERS)
Invoices (INVOIC)
Shipping Notices (DESADV)
Inventory Reports (INVRPT)

Instead of paper, they send structured messages like:

UNH+1+ORDERS:D:96A:UN'
BGM+220+ORDER12345+9'
DTM+137:20240201:102'
...

EDIFACT = UN/EDIFACT Standard

EDIFACT (Electronic Data Interchange For Administration, Commerce and Transport) is the United Nations standard for EDI.

It's used globally, especially in:

🚢 Logistics & Supply Chain
🏭 Manufacturing
🏥 Healthcare
🏛️ Government

EDIFlow = Modern TypeScript Library for EDI

EDIFlow is:

✅ Parser - EDIFACT string → TypeScript objects
✅ Validator - 3-phase validation (Syntax → Structure → Business)
✅ Builder - TypeScript objects → EDIFACT string
✅ Mapper - Auto-convert to/from business objects
✅ Schema Exporter - Generate JSON Schema & TypeScript types

Built with:

Clean Architecture (Uncle Bob)
TypeScript (strict mode)
TDD (599 tests!)
Zero dependencies (core package)

And this is just the beginning! 🚀

Right now, EDIFlow supports EDIFACT (4 versions). But the journey continues:

🔜 X12 (ANSI ASC X12) - Coming soon!
🔜 More EDI formats - We're agile, we follow the flow!
🔜 Community-driven features - What does the community need?

The Clean Architecture foundation makes adding new formats easy. That's the power of good design!

Quick Example:

import { DIContainer } from '@ediflow/core';

// 1. Parse EDIFACT string
const container = DIContainer.getInstance();
const parseUseCase = container.resolve('ParseEDIUseCase');

const result = parseUseCase.execute({
  message: edifactString,
  standard: 'EDIFACT'
});

console.log(result.message.messageType); // "ORDERS"

// 2. Map to business object (type-safe!)
const mapper = container.resolve('BusinessObjectMapper');
const order = mapper.mapToBusinessObject(result.message);

console.log(order.documentNumber);         // "ORDER12345"
console.log(order.parties.buyer.id);       // "BUYER123"
console.log(order.lineItems[0].productId); // IntelliSense works!

// 3. Modify with type safety
order.lineItems[0].quantity = 150;

// 4. Build back to EDIFACT
const buildUseCase = container.resolve('BuildEDIUseCase');
const ediString = buildUseCase.execute({
  message: mapper.mapFromBusinessObject(order),
  standard: 'EDIFACT'
});

This is what "modern EDI" looks like. ✨

6. Project Stats 📊

Let me give you a sneak peek at what we've built so far:

Packages (npm)

Current (EDIFACT):

@ediflow/core - Parser, Validator, Builder engine (MIT)
@ediflow/edifact-d96a - D.96A (1996) - 89 messages (MIT)
@ediflow/edifact-d01b - D.01B (2001) - 155 messages (MIT)
@ediflow/edifact-d20b - D.20B (2020) - 178 messages (MIT)
@ediflow/edifact-d12a - D.12A (2012) - 196 messages (MIT, Prep)

Coming Soon:

@ediflow/x12 - ANSI ASC X12 support 🔜
More formats - We're agile, we follow where "Flow" leads us! 🌊

Current Total: 618 EDIFACT message types supported (and growing!)

Tests & Quality

✅ ~600 tests passing (unit + integration + e2e)
✅ ~90% test coverage (goal: 95%+)
✅ Clean Architecture - All layers tested independently
✅ TypeScript strict mode - No any types!
✅ Zero dependencies (core package)

Architecture

┌───────────────────────────────────────┐
│     Presentation Layer                │  CLI, API, UI (Future)
│                                       │
│  ┌─────────────────────────────────┐ │
│  │   Infrastructure Layer          │ │  Parsers, Repositories
│  │                                 │ │
│  │  ┌───────────────────────────┐  │ │
│  │  │   Application Layer       │  │ │  Use Cases, Services
│  │  │                           │  │ │
│  │  │  ┌─────────────────────┐  │  │ │
│  │  │  │   Domain Layer      │  │  │ │  Entities, Value Objects
│  │  │  └─────────────────────┘  │  │ │
│  │  └───────────────────────────┘  │ │
│  └─────────────────────────────────┘ │
└───────────────────────────────────────┘

Dependency direction: Always inward → → → →

Note: Presentation Layer (CLI, REST API, Web UI) is planned for future releases!

7. What's Coming in This Series? 🗓️

This is just Part 1 of 6! Here's what's next:

Part 1 (This Article): Why? ← You are here! ✅

Motivation & personal story
Why Clean Architecture?
Why TypeScript?
Why Open Source?

Part 2 (Next Week): Domain Layer Deep-Dive

Entities (EDIMessage, Segment)
Value Objects (Delimiters, Standard, Version)
Business Rules (ValidationRule, MandatoryRule)
Real code examples from EDIFlow

Part 3: Application Layer - Use Cases & Services

ParseEDIUseCase, ValidateMessageUseCase, BuildEDIUseCase
ComposableValidationService
DTOs & Dependency Injection
How orchestration works

Part 4: Infrastructure Layer & Monorepo Structure

Parsers (EdifactMessageParser)
Repositories (FileBasedMessageStructureRepository)
Why 5 packages? (Monorepo strategy)
TypeScript project references

Part 5: Presentation Layer - The Interface

CLI tools and commands
REST API design (planned)
Web UI vision (future)
How Presentation Layer stays clean
Dependency Injection from top to bottom

Part 6 (Finale): Lessons Learned & Future

Was Clean Architecture worth it? (honest answer!)
Performance analysis (benchmarks!)
Testing insights (600 tests!)
What I'd do differently
Roadmap & future plans

Each article: 1000-1800 words, deep technical dive with real code!

8. Conclusion & Call to Action 🚀

My Journey

EDIFlow is more than just a library. It's my journey of:

📚 Learning Clean Architecture by doing, not just reading
💙 Proving TypeScript is perfect for enterprise-grade libraries
🌍 Building in public and sharing the process
🔧 Making "old school EDI" developer-friendly
🌊 Following the Flow - Starting with EDIFACT, next X12, then... who knows? We're agile!

It's Not Perfect (Yet!)

I'm not claiming EDIFlow is perfect. I've made mistakes. I've refactored. I've learned.

And that's exactly what this series is about.

In the next 4 articles, I'll show you:

✅ What worked (spoiler: a lot!)
❌ What didn't work (also a lot!)
💡 How to apply Clean Architecture in TypeScript
🚀 Real code from a production-ready library

This is Pair Programming... with You!

I built EDIFlow with GitHub Copilot as my pair programming partner. Now I'm sharing the journey with you.

Follow along, and let's learn together!

🔗 Links & Resources

Try EDIFlow:

Join the Community:

💬 Discord: EDIFlow Community - Real-time chat & support
📣 GitHub Discussions
📧 Email: hello.ediflow@gmail.com

Read More:

💭 What Do YOU Want to Learn?

This series is for you. What topics should I cover?

Domain Layer patterns?
TypeScript DI without frameworks?
Testing strategies?
Performance optimization?

Comment below! 👇

📢 Next Up: Part 2 - Domain Layer

Next week, we'll dive into the Domain Layer:

How do Entities differ from Value Objects?
Why immutability matters
Real code examples from EDIFlow
TypeScript patterns that make Clean Architecture easier

See you next week! 🚀

If you found this helpful:

⭐ Star EDIFlow on GitHub
💬 Join our Discord
📖 Follow this series (click "Follow" on my Dev.to profile!)
🔄 Share with your network

Let's make EDI development great again! 😄

This article is part of the "Building EDIFlow: A Clean Architecture Journey in TypeScript" series. Follow along as we build a production-ready EDIFACT library from scratch using Clean Architecture principles.

Word Count: ~1,650 words

Reading Time: ~7 minutes

Series: Part 1 of 6

Coming Soon:

Part 2: Domain Layer Deep-Dive
Part 3: Application Layer
Part 4: Infrastructure & Packages
Part 5: Presentation Layer
Part 6: Lessons Learned