Add input_transformer/prepare_input hook support to mutation decorator

[evoludigit]

Problem

When building mutations that accept multiple frontend fields that need to be combined/transformed before database storage, there's no hook to perform this transformation.

Real-world example: IP Address + Subnet Mask → CIDR

Frontend sends (GraphQL):

mutation {
  createNetworkConfiguration(input: {
    ipAddress: "192.168.1.1"
    subnetMask: "255.255.255.0"
  })
}

Backend needs (PostgreSQL INET):

INSERT INTO network_config (ip_address) VALUES ('192.168.1.1/24'::inet);

Current Workaround (Doesn't Work)

We tried adding a prepare_input static method to the mutation class:

@fraiseql.mutation(function="create_network_configuration")
class CreateNetworkConfiguration:
    input: CreateNetworkConfigurationInput
    success: CreateNetworkConfigurationSuccess
    failure: CreateNetworkConfigurationError

    @staticmethod
    def prepare_input(input_data: dict) -> dict:
        """Convert IP + subnet mask to CIDR notation."""
        ip = input_data.get("ip_address")
        mask = input_data.get("subnet_mask")
        
        if ip and mask:
            # Convert to CIDR: "192.168.1.1" + "255.255.255.0" → "192.168.1.1/24"
            cidr = parse_ip_input(ip, mask)
            input_data["ip_address"] = cidr
            input_data.pop("subnet_mask", None)
        
        return input_data

Problem: FraiseQL's mutation decorator never calls this method.

Proposed Solution

Add hook support in fraiseql/src/fraiseql/mutations/mutation_decorator.py:

async def resolver(info, input):
    """Auto-generated resolver for PostgreSQL mutation."""
    db = info.context.get("db")
    if not db:
        msg = "No database connection in context"
        raise RuntimeError(msg)

    # Convert input to dict
    input_data = _to_dict(input)

    # NEW: Call prepare_input if defined on mutation class
    if hasattr(self.mutation_class, 'prepare_input'):
        input_data = self.mutation_class.prepare_input(input_data)

    # Call PostgreSQL function
    full_function_name = f"{self.schema}.{self.function_name}"
    # ... rest of resolver

Alternative Names

Consider these hook names:

• prepare_input (current usage in PrintOptim)
• transform_input (more descriptive)
• input_transformer (noun form)

Benefits

1. Clean separation: Frontend schema vs backend storage format
2. Reusable transformations: Same pattern for dates, coordinates, compound fields
3. Type safety: Transformations happen before database call
4. No workarounds: No need for custom resolvers or middleware

Related Use Cases

• Date/time format conversions
• Coordinate conversions (lat/lng → PostGIS point)
• Multi-field combinations (street + city + zip → full address)
• Unit conversions (imperial → metric)

Current Impact

Without this hook, we're forced to:

• ❌ Duplicate IP conversion logic in database functions
• ❌ Handle conversion in GraphQL layer (wrong abstraction)
• ❌ Write custom resolvers (defeats purpose of @fraiseql.mutation)

Compatibility

This is a non-breaking change:

• Existing mutations without prepare_input work unchanged
• Optional hook only runs if defined
• No changes to mutation decorator API

[evoludigit]

✅ Resolved in v0.10.2

This feature has been implemented and released in FraiseQL v0.10.2! 🎉

Implementation

The prepare_input hook is now fully supported in the mutation decorator, exactly as proposed. The hook is called after GraphQL validation but before the PostgreSQL function call.

Location: src/fraiseql/mutations/mutation_decorator.py (lines 113-115)

async def resolver(info, input):
    """Auto-generated resolver for PostgreSQL mutation."""
    # Get database connection
    db = info.context.get("db")
    if not db:
        msg = "No database connection in context"
        raise RuntimeError(msg)

    # Convert input to dict
    input_data = _to_dict(input)

    # ✨ NEW: Call prepare_input hook if defined on mutation class
    if hasattr(self.mutation_class, "prepare_input"):
        input_data = self.mutation_class.prepare_input(input_data)

    # Call PostgreSQL function
    full_function_name = f"{self.schema}.{self.function_name}"
    # ... rest of resolver

Your Example Now Works! ✅

The exact use case you described (IP + subnet mask → CIDR) now works out of the box:

@fraiseql.mutation
class CreateNetworkConfiguration:
    input: CreateNetworkConfigurationInput
    success: CreateNetworkConfigurationSuccess
    error: CreateNetworkConfigurationError

    @staticmethod
    def prepare_input(input_data: dict) -> dict:
        """Convert IP + subnet mask to CIDR notation."""
        ip = input_data.get("ip_address")
        mask = input_data.get("subnet_mask")
        
        if ip and mask:
            cidr_prefix = {
                "255.255.255.0": 24,
                "255.255.0.0": 16,
                "255.0.0.0": 8,
            }.get(mask, 32)
            
            return {
                "ip_address": f"{ip}/{cidr_prefix}",
                # subnet_mask is removed
            }
        return input_data

Result:

• Frontend sends: { ipAddress: "192.168.1.1", subnetMask: "255.255.255.0" }
• Database receives: { ip_address: "192.168.1.1/24" }

Bonus Feature: Empty String → NULL Conversion

v0.10.2 also includes automatic empty string to None conversion for optional fields, which complements the prepare_input hook nicely:

• Optional fields (notes: str | None): Accept "", automatically convert to None
• Required fields (name: str): Reject "" with validation error

Test Coverage

• ✅ 3 new prepare_input hook tests
• ✅ 6 new empty string conversion tests
• ✅ All 3,295 existing tests pass (no regressions)
• ✅ 100% backward compatible

Documentation

Comprehensive documentation added to the mutation decorator docstring with multiple examples:

• IP + subnet mask → CIDR (your use case)
• Empty string normalization
• Additional transformation patterns

Full release notes: RELEASE_NOTES_v0.10.2.md

Installation

pip install fraiseql==0.10.2

or with uv:

uv add fraiseql==0.10.2

Related Links

• Release: https://github.com/fraiseql/fraiseql/releases/tag/v0.10.2
• PyPI: https://pypi.org/project/fraiseql/0.10.2/
• PR: 🚀 Release v0.10.2 - Mutation Input Transformation and Empty String Handling #76
• Commits:
  • 58dc9a8 - Add prepare_input hook and empty string conversion
  • c23f5f1 - Bump version to 0.10.2

Thank you for the detailed feature request! The implementation follows your proposed design exactly. 🚀