[EE-3024] support inline fragments

[thomaschaplin]

Add inline fragments support

This PR fixes issue - #52

Summary

This PR implements comprehensive support for GraphQL inline fragments (... on TypeName) in the graphql-query-to-json library. Inline fragments enable conditional field selection based on GraphQL union and interface types, making this library a complete complement to the json-to-graphql-query library.

Problem

The library previously did not support GraphQL inline fragments, which are essential for working with union types and interfaces. This limitation prevented users from processing queries that conditionally select fields based on concrete types.

# This syntax was not supported
query {
    posts {
        title
        ... on TextPost {
            content
        }
        ... on ImagePost {
            imageUrl
        }
    }
}

Solution

Implementation Details

Core Changes:

• Updated Selection interface to include typeCondition for inline fragments
• Enhanced getSelections() function to process InlineFragment AST nodes
• Added recursive processing for nested inline fragments
• Maintained full compatibility with existing functionality

JSON Output Format:

• Single inline fragment: __on: { __typeName: "TypeName", ...fields }
• Multiple inline fragments: __on: [{ __typeName: "Type1", ...}, { __typeName: "Type2", ...}]

This format mirrors the json-to-graphql-query library's approach, ensuring seamless bidirectional conversion.

Features Supported

• ✅ Single and multiple inline fragments
• ✅ Nested inline fragments with proper recursion
• ✅ Arguments within inline fragments (including enums and variables)
• ✅ Field aliases within inline fragments
• ✅ Complex nested structures within fragments
• ✅ Full variable substitution within fragments

Examples

Single Inline Fragment

query {
    posts {
        title
        ... on TextPost {
            content
            wordCount
        }
    }
}

Output:

{
  "query": {
    "posts": {
      "title": true,
      "__on": {
        "__typeName": "TextPost",
        "content": true,
        "wordCount": true
      }
    }
  }
}

Multiple Inline Fragments

query {
    media {
        ... on TextPost {
            content
        }
        ... on ImagePost {
            imageUrl
            altText
        }
        ... on VideoPost {
            videoUrl
            duration
        }
    }
}

Output:

{
  "query": {
    "media": {
      "__on": [
        {
          "__typeName": "TextPost",
          "content": true
        },
        {
          "__typeName": "ImagePost", 
          "imageUrl": true,
          "altText": true
        },
        {
          "__typeName": "VideoPost",
          "videoUrl": true,
          "duration": true
        }
      ]
    }
  }
}

Testing

Comprehensive Test Coverage

• 8 new test cases covering all inline fragment scenarios:

  • Single and multiple inline fragments
  • Nested inline fragments
  • Fragments with arguments and variables
  • Fragments with enum arguments
  • Fragments with aliases
  • Complex nested structures within fragments

• 3 README example tests ensuring documentation accuracy

• Updated existing tests to reflect inline fragments now work (converted error test to success test)

Test Results: ✅ All 75 tests passing

Documentation Updates

README.md Changes

• Features section: Added inline fragments to supported features list
• Transformation rules table: Added inline fragment transformation mapping
• New inline fragments section: 3 comprehensive examples with expected outputs
• Updated limitations section: Changed inline fragments from "not supported" to "fully supported"

Compatibility

• Backward compatible: No breaking changes to existing API
• TypeScript support: Full type safety maintained
• json-to-graphql-query alignment: Uses identical __on format for seamless interoperability

Related Issues

Resolves the inline fragments limitation discussed in PR #23.

Breaking Changes

None. This is a purely additive feature that maintains full backward compatibility.

---

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

[thomaschaplin]

@rickschubert please can you review this PR?

[rickschubert]

This looks great!

I have a few comments but these are all readme related. The feature itself works well. Great work!