Skip to content

README.md

Latest commit

 

History

History
68 lines (42 loc) · 4.15 KB

README.md

File metadata and controls

68 lines (42 loc) · 4.15 KB
Raw

Mammoth.LiteMapper

Mammoth.LiteMapper is a convention-first, compile-time object mapping library for C#.

Consumers declare partial mapping methods on classes marked with [LiteMapper]. A Roslyn incremental source generator emits direct C# implementations using constructors, assignments, loops, casts, and ordinary method calls. LiteMapper is not a runtime mapping container and does not provide runtime mapper registration, assembly scanning, reflection fallback, or dynamic dispatch.

Assembly-wide defaults and external mapper registrations are compile-time configuration. Rebuild after changing them. Generated helpers are private; call only the mapping methods you declare and do not depend on helper names or signatures.

Compilation Status

  • main CI
  • develop CI

Quickstart

Install the latest stable primary package in a project without central package management:

dotnet add package Mammoth.LiteMapper

For central package management, put the version in Directory.Packages.props instead; see installation. When upgrading from an earlier release, follow the migration guide, covering 1.0.0 to 2.0.0, 2.0.0 to 3.0.0, and 3.0.0 to 4.0.0. Corrected member matching, collection equality, null handling, and converter selection can affect existing mappings.

Declare a mapper:

using Mammoth.LiteMapper;

[LiteMapper]
public static partial class CustomerMapper
{
    public static partial CustomerDto Map(Customer source);
}

Use the generated method like ordinary C#:

CustomerDto dto = CustomerMapper.Map(customer);

See the compiling samples under samples/ for static mappers, instance mappers, collections, recursive mappings, and ASP.NET Core usage.

Ordinary unmapped target members are reported as LITEMAPPER1001 errors by default. Explicit mapper or method UnmappedMemberPolicy values and standard compiler severity configuration may intentionally relax this configurable diagnostic; doing so preserves valid generation but is not proof of complete target coverage. Required, non-nullable, inaccessible, invalid, and otherwise mandatory target obligations remain hard errors. Projects requiring mandatory unmapped-target coverage should treat LITEMAPPER1001 as an error in CI and audit or avoid project-wide suppression.

Documentation

  • SPECIFICATION.md is the sole authoritative product contract.
  • USAGE.md is the usage guide and must stay synchronized with the specification, samples, tests, and other project documents.

Agent skill

The mammoth-litemapper skill provides consumer mapping guidance for compatible coding agents using the Skills CLI.

Install the skill from main for the latest guidance. This branch can change as the project develops:

npx skills add https://github.com/PrimordialCode/Mammoth.LiteMapper/tree/main/skills/mammoth-litemapper --skill mammoth-litemapper

To install guidance from a release tag, replace <tag-version> below with an existing tag matching your NuGet package version, for example 4.0.0 (without a v prefix):

npx skills add "https://github.com/PrimordialCode/Mammoth.LiteMapper/tree/<tag-version>/skills/mammoth-litemapper" --skill mammoth-litemapper

Append --agent codex to target Codex or --global for user-level installation. To preview this checkout without installing, run npx skills add ./skills/mammoth-litemapper --list from the repository root. The skill includes its supporting reference and needs no source checkout. Installing the skill does not upgrade the NuGet package; check the application's package version and follow the migration steps when upgrading.