OpenParable
Skip to content
← Back to skills

Mapperly

Development
mapperly

Mapperly is an Agent Skill for development published in the recyclarr/recyclarr repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when writing, editing, or reviewing Mapperly (`Riok.Mapperly`) mapper classes; adding or changing a `[Mapper]`-attributed partial class; configuring `RequiredMappingStrategy`, `[MapProperty]`, `[MapperIgnore]`, or other Mapperly attributes; mapping between nullable Refit/OpenAPI DTOs and non-nullable domain records; debugging null-handling in generated mapping code (positional records, `required init`, initializer defaults); investigating Mapperly diagnostics such as RMG001, RMG020, or RMG089; inspecting source-generated output under `obj/Debug/*/generated/Riok.Mapperly/`. Triggers on phrases like "add a Mapperly mapper", "Mapperly null handling", "DTO to domain mapping", "generated mapper", or edits to files ending in `*Mapper.cs` under `ServarrApi/`. Do NOT use for hand-written mapping code or AutoMapper.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/recyclarr/recyclarr/blob/HEAD/.opencode/skills/mapperly/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/mapperly, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Mapperly

Conventions and null-handling semantics for Mapperly source-generated mappers.

Mapper Conventions

  • [Mapper(RequiredMappingStrategy = RequiredMappingStrategy.None)] on every mapper. Generated DTOs have many properties we don't map; this silences unmapped-property warnings.
  • One mapper class per service (Sonarr/Radarr). Generated DTO types share names but are distinct types from separate packages.
  • Namespace aliases disambiguate: using SonarrApi = Recyclarr.Api.Sonarr.
  • Mappers are internal static partial class.

Null Handling (nullable DTO -> non-nullable domain)

Generated Refit DTOs mark all properties as nullable (T?). Domain models use non-nullable types for fields that should always have a value. Mapperly handles the mismatch differently depending on the target shape.

Constructor parameters (positional records)

Mapperly substitutes type-appropriate defaults when the source is null:

  • string? -> string: "" (empty string)
  • T? where T has a parameterless constructor: new T()
  • T? value type: default(T)

Init properties without initializers

Mapperly generates throw ArgumentNullException when the source is null. This is hardcoded for required init properties regardless of mapper settings.

Init/setter properties with initializers (e.g. = "", = [])

Mapperly skips the assignment when the source is null. The initializer value is preserved. This is the safest pattern for "optional with sensible default" semantics.

Setter properties without initializers

Mapperly skips the assignment. The property stays at default(T), which for reference types is null. This silently violates the non-nullable contract. Avoid this shape for non-nullable reference types.

Nullable target properties

Assigned directly, including null. No special handling.

RMG089 Diagnostic

"Mapping nullable source property X to target property Y which is not nullable." Default severity: Info. This diagnostic is informational; the generated code handles the mismatch using the rules above. No suppression or severity promotion is needed.

Inspecting Generated Code

To see what Mapperly actually generates, temporarily add to Directory.Build.props:

<EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>

Output appears in obj/Debug/<tfm>/generated/Riok.Mapperly/Riok.Mapperly.MapperGenerator/. Remove the property when done.