feat: migrations at the resource layer.

[subomi]

Overview

RequestMigrations v2 introduces a type-based migration system that replaces the original handler-based approach. Instead of defining migrations per API handler (e.g., createUserRequestMigration), migrations are now defined per Go type (e.g., AddressMigration for the Address struct).

Key Features

• Type-Centric: Migrations are defined per Go type, ensuring they are applied everywhere the type appears.
• Automatic Graph Resolution: Nested types are migrated automatically by building a type dependency graph.
• Bidirectional: Support for both forward (request) and backward (response) migrations.
• Generic Registration: Uses Go generics for type-safe registration and zero boilerplate.
• Cycle Detection: Handles circular references (e.g., User → Workspace → User) during graph construction.
• Graph Caching: Thread-safe caching of compiled graphs for high performance.

Design

The system builds a type dependency graph to handle nested structs and cycles, applying migrations recursively through the object graph.

Internal Pivot

While the public API is version-centric, the internal storage is now type-centric (map[reflect.Type]map[string]TypeMigration), allowing for efficient graph construction.

Usage

// Register a migration for a type
rms.Register[User](rm, "2024-01-01", &UserMigration{})

// Use in handlers
rm.WithUserVersion(r).Marshal(&user)
rm.WithUserVersion(r).Unmarshal(body, &user)

Status

• TypeMigration interface
• TypeGraph construction with DFS
• Cycle detection & memoization
• Generic Registration API
• Nested struct & Slice handling
• Support for custom primitive types