dto-serialization_skill

Overview

This skill guides creating and maintaining DTOs and their (de)serialization using Dart Data Class Generator directives (without freezed/json_serializable). It focuses on immutable DTOs, explicit field mapping for complex types, and deterministic nested parsing to keep serialization safe and testable. The guidance is practical and geared toward Flutter/Dart projects that avoid codegen build_runner models.

How this skill works

You annotate immutable classes with field-level directives in comments ($from and $to) to teach the generator how to parse and serialize non-primitive fields. The VS Code Dart Data Class Generator reads these directives and produces fromMap/toMap implementations. Round-trip tests validate critical DTOs to ensure mapping stability across changes.

When to use it

• Creating a new DTO for API payloads or local persistence.
• Adding fields that require custom mapping (DateTime, Duration, enums, colors).
• Modeling nested lists or nested DTOs that require explicit parsing.
• Enforcing a no-freezed/json_serializable policy for models.
• Preparing DTOs used in cross-feature contracts or network boundaries.

Best practices

• Define DTOs as immutable: use @immutable, final fields, and a const constructor.
• Use $from and $to directives for any non-primitive field to keep mapping explicit.
• Prefer safe enum lookup with fallback instead of Enum.byName for untrusted input.
• Parse nested lists/maps deterministically and avoid nullable surprises with defaults.
• Add round-trip tests for DTOs used in persistence or inter-service contracts.

Example use cases

• OrderDto with createdAt (ISO string), timeout (milliseconds), and status enum with safe parsing.
• Parsing a list of OrderItemDto from a nested JSON array using explicit map-to-DTO mapping.
• Mapping a color int with a default fallback and serializing it back unchanged.
• Serializing Duration fields to integer seconds/milliseconds for compact wire format.
• Validating that toMap/fromMap round-trip preserves business-critical fields in tests.