Get started with TwinMapper

Installation

TwinMapper is distributed as Maven artifacts under the net.sphuta.twinmapper group ID. Add the Spring Boot starter to your project:

<dependency>
  <groupId>net.sphuta.twinmapper</groupId>
  <artifactId>twinmapper-spring-boot-starter</artifactId>
  <version>1.0.0</version>
</dependency>

For build-time code generation, add the Maven or Gradle plugin:

<plugin>
  <groupId>net.sphuta.twinmapper</groupId>
  <artifactId>twinmapper-maven-plugin</artifactId>
  <version>1.0.0</version>
</plugin>

Quickstart

1. Write a YAML definition

Create a definition file using the TwinMapper-native YAML DSL. This single file drives DTO generation, binder generation, validator generation, and metadata generation:

definitionSet:
  name: order-model
  version: "1.0"
  basePackage: com.example.orders

types:
  - name: OrderRequest
    fields:
      - name: orderId
        type: string
        required: true
      - name: quantity
        type: integer
        constraints:
          min: 1
          max: 10000
      - name: status
        type: enum
        values: [DRAFT, SUBMITTED, APPROVED]

2. Run code generation

The build plugin scans your definition directory, parses definitions into the internal DefinitionSet meta-model, and runs the five-stage pipeline:

3. Bind at runtime

Use the generated binder to bind runtime YAML or JSON documents into typed DTOs:

BindingResult<OrderRequest> result =
    twinMapperRuntime.readYaml(inputStream, OrderRequest.class);

if (result.hasErrors()) {
    // Handle accumulated binding errors
} else {
    OrderRequest order = result.getValue();
}

Document Engine

The Document Engine reads fixed YAML, JSON, and BPMN definitions at build time. It generates DTOs, enums, binders, validators, registries, and metadata. At runtime, it binds actual documents into generated DTOs using the NodeCursor abstraction — no reflection at binding time.

The binding pipeline: Runtime Document → Format Parser → NodeCursor → Generated Binder → Generated DTO → BindingResult<T>.

Object Engine

The Object Engine generates typed Java-to-Java mappers for layer-crossing flows. It supports entity↔domain, domain↔DTO, DTO↔entity, entity↔projection, request/command↔domain, and domain↔event/view/response.

Three mapper modes: CREATE (new target, SET_NULLS default), UPDATE (existing target, IGNORE_NULLS default, preserves identity/audit fields), and PATCH (existing target, IGNORE_NULLS enforced, non-configurable).

Module Architecture

TwinMapper contains 14 core modules organized into five families: Core (core, definition-model, codegen, validation), Runtime (runtime, runtime-binding, runtime-objectmap), Format (format-json, format-yaml, format-bpmn), Tooling (gradle-plugin, maven-plugin, cli), and Integration (spring-boot-starter).

The dependency spine is linear: core → definition-model → format-* → codegen → runtime → runtime-binding → runtime-objectmap → validation → spring-boot-starter. Build plugins consume codegen orthogonally.

Binding Spec

The Document Binding Specification covers the NodeCursor contract, BindingContext configuration, BindingResult semantics, error accumulation behavior, alias resolution, default value population, required-field enforcement, and unknown-field rejection.

NodeCursor Contract

NodeCursor is the core runtime abstraction separating format parsing from binding logic. It provides field existence checks, required/optional scalar reads, enum reads, nested object access, list/map children, source location tracking, field path diagnostics, and depth limiting.

SPI and Extension Guide

TwinMapper provides seven SPIs: DefinitionReader, RuntimeDocumentParser, ValidationExtension, ValueConverter, CodegenCustomizer, TwinMapperRuntimeConfigurer, and ConventionMappingResolver. All follow Spring's ordering model via OrderComparator.

Release Notes

Phase 3 (Code Generation) is complete. The five-stage pipeline with all 11 generators is operational. Phases 4–10 (Runtime Platform, Build Plugins, Spring Boot Starter, CLI, and Optional Extensions) are pending.