Add GroupJoin overload returning IGrouping

[Copilot]

Implements the approved API from #120587 — a simplified GroupJoin overload that removes the need for an explicit result selector, returning IGrouping<TOuter, TInner> where the outer element is the key and the correlated inner elements are the grouping contents.

Description

API

namespace System.Linq;

public static partial class Enumerable
{
    public static IEnumerable<IGrouping<TOuter, TInner>> GroupJoin<TOuter, TInner, TKey>(
        this IEnumerable<TOuter> outer,
        IEnumerable<TInner> inner,
        Func<TOuter, TKey> outerKeySelector,
        Func<TInner, TKey> innerKeySelector,
        IEqualityComparer<TKey>? comparer = null);
}

public static partial class Queryable
{
    public static IQueryable<IGrouping<TOuter, TInner>> GroupJoin<TOuter, TInner, TKey>(
        this IQueryable<TOuter> outer,
        IEnumerable<TInner> inner,
        Expression<Func<TOuter, TKey>> outerKeySelector,
        Expression<Func<TInner, TKey>> innerKeySelector,
        IEqualityComparer<TKey>? comparer = null);
}

public static partial class AsyncEnumerable
{
    public static IAsyncEnumerable<IGrouping<TOuter, TInner>> GroupJoin<TOuter, TInner, TKey>(
        this IAsyncEnumerable<TOuter> outer,
        IAsyncEnumerable<TInner> inner,
        Func<TOuter, TKey> outerKeySelector,
        Func<TInner, TKey> innerKeySelector,
        IEqualityComparer<TKey>? comparer = null);

    public static IAsyncEnumerable<IGrouping<TOuter, TInner>> GroupJoin<TOuter, TInner, TKey>(
        this IAsyncEnumerable<TOuter> outer,
        IAsyncEnumerable<TInner> inner,
        Func<TOuter, CancellationToken, ValueTask<TKey>> outerKeySelector,
        Func<TInner, CancellationToken, ValueTask<TKey>> innerKeySelector,
        IEqualityComparer<TKey>? comparer = null);
}

Changes

• System.Linq: New GroupJoin<TOuter,TInner,TKey> overload with optional IEqualityComparer<TKey>? parameter + internal GroupJoinGrouping<TKey, TElement> wrapper class. XML doc comments with correct <see cref="IGrouping{TOuter, TInner}"/> references added to the new public API.
• System.Linq.Queryable: New overload with optional IEqualityComparer<TKey>? parameter and [DynamicDependency] on Enumerable.GroupJoin3`. XML doc comments added.
• System.Linq.AsyncEnumerable: Two new overloads (sync and async key selector variants) with optional IEqualityComparer<TKey>? parameter + internal AsyncGroupJoinGrouping<TKey, TElement> wrapper class. XML doc comments added.
• Reference assemblies updated for all three projects.
• Tests for all three projects, with #if NET guards in the async enumerable tests for net481 compatibility (the new Enumerable.GroupJoin overload and tuple-returning Zip are unavailable on .NET Framework 4.8.1).

[eiriktsarpalis]

@copilot you forgot to add the corresponding IAsyncEnumerable overloads in the System.Linq.AsyncEnumerable project.

[Copilot]

@copilot you forgot to add the corresponding IAsyncEnumerable overloads in the System.Linq.AsyncEnumerable project.

Added the IAsyncEnumerable GroupJoin overloads (both sync and async key selector variants) in commit 05ca46a.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-linq
See info in area-owners.md if you want to be subscribed.

[stephentoub]

@copilot please invoke the code-review skill and post your analysis/results as comment on this PR

[Copilot]

@copilot please invoke the code-review skill and post your analysis/results as comment on this PR

🤖 Copilot Code Review

Holistic Assessment

Motivation: The PR implements an approved API (issue #120587, api-approved label) to add simplified GroupJoin overloads without a resultSelector, returning IGrouping<TOuter, TInner>. This is consistent with the pattern established by the simplified Zip overload and the approved API review.

Approach: The implementation follows the existing patterns in each project (Enumerable, Queryable, AsyncEnumerable) closely, delegating to existing Lookup/AsyncLookup infrastructure and wrapping results in a new internal GroupJoinGrouping type. This is the right approach.

Summary: ⚠️ Needs Human Review. The implementation is functionally correct and follows existing patterns well, but has several issues ranging from missing XML documentation on new public APIs to a duplicated internal type that could be consolidated.

---

Detailed Findings

⚠️ Missing XML documentation on new Enumerable and Queryable public APIs

The new Enumerable.GroupJoin overloads (lines 11-12 and 14 of GroupJoin.cs) and the new Queryable.GroupJoin overloads (lines 411-424 and 426-439 of Queryable.cs) have no XML doc comments. Per dotnet/runtime conventions, all new public APIs must have /// XML doc comments since they seed the official API documentation on learn.microsoft.com. The AsyncEnumerable overloads do have XML docs, which makes the inconsistency more noticeable.

The existing GroupJoin overloads with resultSelector in Enumerable also lack XML docs (they predate this PR), so while it's not a regression, adding docs to the new overloads would be the right thing to do for new API surface. The Queryable existing overloads do have docs for the Join overload nearby, so the new GroupJoin ones should follow suit.

⚠️ Duplicated GroupJoinGrouping / AsyncGroupJoinGrouping types

GroupJoinGrouping<TKey, TElement> in System.Linq (lines 113-129) and AsyncGroupJoinGrouping<TKey, TElement> in System.Linq.AsyncEnumerable (lines 262-278) are identical except for the name. Since they are internal in different assemblies this is technically necessary, but it's worth noting. One option would be placing it in a shared source file via <Compile Include="..." Link="..." />, consistent with how other shared types are handled in the repo. This is a minor suggestion — the current approach works and avoids coupling.

💡 The Enumerable GroupJoin without comparer could delegate more simply

Currently the no-comparer overload (line 11) delegates to the comparer overload:

public static IEnumerable<IGrouping<TOuter, TInner>> GroupJoin<TOuter, TInner, TKey>(...) =>
    GroupJoin(outer, inner, outerKeySelector, innerKeySelector, comparer: null);

This means the null checks in the comparer overload execute, which is fine. But note the existing GroupJoin<TOuter, TInner, TKey, TResult> with resultSelector follows the same pattern (line 44 delegates to line 47), so this is consistent. ✅

✅ Correctness of Queryable DynamicDependency annotations

The new Queryable overloads correctly use [DynamicDependency("GroupJoin3", typeof(Enumerable))](note the backtick-3, matching the 3 generic type parameters of the new Enumerable overload). This is correct and consistent with the existing"GroupJoin4" annotations on the 4-type-param overloads.

✅ Implementation follows existing iterator patterns

The new GroupJoinIterator (lines 82-95) correctly mirrors the existing one (lines 97-110) with the only difference being the yield return wrapping. The Lookup indexer returns Enumerable.Empty<TElement>() for missing keys, so the GroupJoinGrouping always wraps a valid IEnumerable<TInner>.

✅ AsyncEnumerable implementation follows existing patterns

The new async overloads (lines 31-67 and 87-126) correctly follow the same structure as the existing result-selector overloads: null checks, IsKnownEmpty() optimization, Impl local function with [EnumeratorCancellation], and proper await using of the enumerator.

✅ Ref assemblies are correctly updated

All three ref assemblies (System.Linq.cs, System.Linq.Queryable.cs, System.Linq.AsyncEnumerable.cs) have the new overloads added in the correct alphabetical position.

✅ Test coverage is adequate

Tests cover: empty outer, empty inner, matches, multi-element matches, null argument validation for all parameters, custom comparer, and re-iterability of results. The async tests cover both sync and async key selector variants, input validation, empty optimization, values matching, and interface call counts.

[Copilot]

@copilot fix the doc errors signaled above.

Fixed in commit 5302dce. The doc errors were <see cref="IGrouping{TKey, TElement}"/> using TElement which isn't a type parameter of the new methods — replaced with <see cref="IGrouping{TOuter, TInner}"/> in all 4 locations. Also fixed a net481 compilation failure in VariousValues_WithoutResultSelector_MatchesEnumerable where the test was calling our new Enumerable.GroupJoin without result selector (not available in .NET Framework) and the tuple-returning Zip overload (also not available on net481).

[roji]

@copilot revert the test change in your last commit - VariousValues_WithoutResultSelector_MatchesEnumerable is explicitly about calling the overload without the result selector, as the name suggests.

[Copilot]

@copilot revert the test change in your last commit - VariousValues_WithoutResultSelector_MatchesEnumerable is explicitly about calling the overload without the result selector, as the name sugges...

Restored the original test form in commit 488b542. Wrapped the body in #if NET to handle the net481 compilation issue (following the established pattern in the test project, e.g. AppendTests.cs, ChunkTests.cs, etc.) — the new Enumerable.GroupJoin without result selector and the tuple-returning Zip are both unavailable on net481.

[github-actions]

🤖 Copilot Code Review — PR #121999

Note

This review was generated by Copilot.

Holistic Assessment

Motivation: Justified — the existing GroupJoin always requires a resultSelector delegate, forcing callers to write boilerplate (outer, inners) => new { outer, inners }. The new overload returns IGrouping<TOuter, TInner> directly, which is more ergonomic and consistent with how GroupBy works. Approved in #120587.

Approach: Good — the implementation closely mirrors the existing GroupJoinIterator pattern, introduces a thin GroupJoinGrouping wrapper, and covers Enumerable, Queryable, and AsyncEnumerable consistently. The new internal types are minimal and sealed.

Summary: ✅ LGTM. The implementation matches the approved API shape from #120587 (including the v2 with IEqualityComparer and async overloads approved by @eiriktsarpalis). The code follows existing codebase patterns, has good test coverage, and introduces no correctness or performance concerns.

---

Detailed Findings

✅ API Approval Verification — Matches approved shape

Issue #120587 has the api-approved label. The initial shape was approved by @bartonjs, and the v2 (adding IEqualityComparer<TKey>? comparer = null and AsyncEnumerable overloads) was approved by @eiriktsarpalis. The implementation matches the approved API exactly:

• Enumerable.GroupJoin<TOuter, TInner, TKey> with optional comparer ✅
• Queryable.GroupJoin<TOuter, TInner, TKey> with optional comparer ✅
• AsyncEnumerable.GroupJoin<TOuter, TInner, TKey> — both sync and async key selector variants ✅

Ref assembly entries are present for all three libraries. No unapproved public API surface detected.

✅ Implementation Correctness — Follows existing patterns

• System.Linq: Uses ThrowHelper for null checks (matching the existing GroupJoin<..., TResult> overload in the same file), delegates to Lookup<TKey, TInner>.CreateForJoin which correctly returns empty enumerables for unmatched keys, and uses IsEmptyArray for the fast-path optimization.
• AsyncEnumerable: Uses ArgumentNullException.ThrowIfNull (matching the existing pattern in that library), IsKnownEmpty() for the fast path, and properly threads CancellationToken via [EnumeratorCancellation].
• Queryable: Correctly builds the expression tree with DynamicDependency("GroupJoin3", typeof(Enumerable))` referencing the new 3-type-parameter overload.

The new GroupJoinGrouping(TKey, TElement) and AsyncGroupJoinGrouping(TKey, TElement) are internal sealed and provide a clean wrapper for the key + elements pairing. They are separate types because they live in different assemblies — this duplication is consistent with other Linq/AsyncEnumerable type pairs in the codebase.

✅ Test Coverage — Comprehensive

Tests cover:

• Empty outer/inner sequences
• Single/multiple matching elements
• Null argument validation for all parameters (outer, inner, outerKeySelector, innerKeySelector)
• Custom IEqualityComparer (via AnagramEqualityComparer)
• Multiple iteration of grouped elements
• Async variants with interface call counting
• #if NET guards in async tests (necessary since Enumerable.GroupJoin 3-param overload isn't available on .NET Framework)

✅ XML Documentation — Correct

The (see cref) references correctly use IGrouping{TOuter, TInner} (not the generic IGrouping{TKey, TElement}), which was fixed per earlier review feedback. All new public APIs have complete XML documentation including <summary>, (typeparam), (param), (returns), and (exception) tags.

💡 Suggestion — Minor: GroupJoinGrouping could use primary constructor

GroupJoinGrouping(TKey, TElement) could use a C# 12 primary constructor to reduce boilerplate (internal sealed class GroupJoinGrouping(TKey, TElement)(TKey key, IEnumerable(TElement) elements) : IGrouping(TKey, TElement)). However, the existing Grouping(TKey, TElement) in the same codebase uses explicit constructors, so the current style is consistent.

Generated by Code Review for issue #121999 · ◷

[eiriktsarpalis]

@copilot Please fix the merge conflicts.

[Copilot]

@copilot Please fix the merge conflicts.

Resolved in merge commit e9ff7d5. The conflict was in Queryable.cs where the new Join<TOuter,TInner,TKey> overload from #120596 was inserted at the same location as our GroupJoin<TOuter,TInner,TKey> overload — kept both methods.

[eiriktsarpalis]

@copilot you did not fix the merge conflicts. Please try again.

[Copilot]

@copilot you did not fix the merge conflicts. Please try again.

Fixed in merge commit 72dae6c. The conflict was in Queryable.cs where our GroupJoin<3> overload conflicted with the empty section after #121998 removed the duplicate that was introduced by the prior incorrect merge. The merge now has proper two-parent history (our branch + main).

[eiriktsarpalis]

/ba-g tests are passing