Add a GroupJoin overload without a result selector, returning an IGrouping

[Thaina]

Motivation and Background

GroupJoin currently forces users to pass in a result selector which determines the shape of the return type. In most basic usages, users project out to an anonymous type (or a tuple) which wraps the returned TInner and TOuters - this proposal adds an additional overload of GroupJoin that removes to need to specify a result selector, and returns a tuple. We expect this will cover and simplify a large majority of the use-cases.

This proposal mirrors the simplified Zip overload, and also #120596 for Join.

API Proposal

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 class AsyncEnumerable
{
    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);

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

Usage

var departments = new List<Department>
{
    new() { Id = 1, Name = "HR" },
    new() { Id = 2, Name = "IT" },
    new() { Id = 3, Name = "Finance" }
};

var employees = new List<Employee>
{
    new() { Name = "Alice", DepartmentId = 1 },
    new() { Name = "Bob", DepartmentId = 2 },
    new() { Name = "Charlie", DepartmentId = 2 },
    new() { Name = "David", DepartmentId = 3 }
};

// New proposed simplified usage:
foreach (var (emp, depts) in employees.GroupJoin(departments, e => e.DepartmentId, d => d.Id))
{
    Console.WriteLine($"Employee: {emp.Name}, departments: {string.Join(", ", depts.Select(i => i.Name))}");
}

// Existing usage: explicit projection out to tuple required
foreach (var (emp, depts) in employees.GroupJoin(departments, e => e.DepartmentId, d => d.Id, (e, d) => (e, d)))
{
    Console.WriteLine($"Employee: {emp.Name}, departments: {string.Join(", ", depts.Select(i => i.Name))}");
}

class Department
{
    public int Id { get; set; }
    public string Name { get; set; }
}

class Employee
{
    public string Name { get; set; }
    public int DepartmentId { get; set; }
}

[dotnet-policy-service]

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

[KalleOlaviNiemitalo]

public static IEnumerable<IGrouping<TKey, TResult>> GroupJoin<TOuter, TInner, TKey, TResult>(this IEnumerable<TOuter> outer, IEnumerable<TInner> inner, Func<TOuter, TKey> outerKeySelector, Func<TInner, TKey> innerKeySelector);

TResult cannot be deduced from those arguments. Where do the TResult values come from?

[Thaina]

Sorry let me fix it

[KalleOlaviNiemitalo]

If I understand your proposal correctly, the Enumerable side would be equivalent to the following, but more efficient:

using System;
using System.Collections;
using System.Collections.Generic;

static partial class Enumerable
{
    public static IEnumerable<System.Linq.IGrouping<(TKey, TOuter), TInner>> GroupJoin<TOuter, TInner, TKey>(
        this IEnumerable<TOuter> outer,
        IEnumerable<TInner> inner,
        Func<TOuter, TKey> outerKeySelector,
        Func<TInner, TKey> innerKeySelector)
    {
        return System.Linq.Enumerable.GroupJoin(
            outer,
            inner,
            outerKeySelector,
            innerKeySelector,
            resultSelector: (TOuter outer, IEnumerable<TInner> inners) =>
                new Grouping<(TKey, TOuter), TInner>((outerKeySelector(outer), outer), inners));
    }
}

internal sealed class Grouping<TKey, TElement>(TKey key, IEnumerable<TElement> elements)
    : System.Linq.IGrouping<TKey, TElement>
{
    public TKey Key => key;
    public IEnumerator<TElement> GetEnumerator() => elements.GetEnumerator();
    IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
}

The Queryable side would presumably just build an expression tree and call source.Provider.CreateQuery<TResult>, like the other methods there. System.Linq.EnumerableRewriter might not need any changes.

[Thaina]

Correct, in actuality I just want the API to be flatten tuple like Zip for convenient to be used in linq and foreach

[eiriktsarpalis]

Why wouldn't this return (TOuter, IEnumerable<TInner>) following the spirit of your other proposal in #120596?

[Thaina]

@eiriktsarpalis 1 - Because IGrouping is already established interface for group of object with Key. It would be more familiar for people
2 - Because it has already has another function with similar signature. For Join it was more similar to Zip while GroupJoin is more similar to GroupBy
3 - IGrouping can iterate by itself

[roji]

I think it's problematic for the returned IGrouping to have (TKey, TOuter) as its key:

• For one thing, Join returns only TOuter and TInner (no key); the same question has been raised for the proposed simplified Join syntax (should it also return the keys?), and that proposal doesn't return the key for (I believe) reasons which apply here as well.
• Just like for Join, the current result selectors for the existing GroupJoin (and Join) accept only the outers and inners, and not the key. If one really wants the keys, one can always reference them again on the outer/inner inside the selector; so there's no reason to impose the extra complexity on everyone, and for the few who do need the key, they can get it (at least for cases where the key selector isn't a complex expression that's potentially expensive to evaluate).
• Having the IGrouping have its TKey be a tuple of the GroupJoin's TKey and TOuter is, well, quite confusing and unwieldy, as TKey means two completely different things (it's the correlation key within GroupJoin, and the tuple of the correlation key and the outer within the IGrouping).

Because of the above, I think it would make more sense (and be more consistent) for GroupJoin to return TOuter and the enumerable of correlated TInners. @eiriktsarpalis you suggested this above - but with a tuple as opposed to an IGrouping. I do agree with @Thaina that IGrouping has the advantage of being directly enumerable without having to dot in. But one slight problem with IGrouping is that its generic type parameter is named TKey, and it would be (again) problematic to have that contain the TOuter of the GroupJoin... The sample above obscures this slightly since the outer key selector simply returns TOuter itself as the key (key => key).

I admit that this really is a relatively minor naming concern: if we really want to, we could introduce another IGrouping-like interface to address this (it would be identical to IGrouping except for having the type parameter called TOuter instead of TKey). Or we could be OK with IGrouping's TKey referring to the GroupJoin's TOuter, or just return a tuple as @eiriktsarpalis suggested (dotting into the tuple in order to enumerate isn't the end of the world).

[roji]

Discussed offline with @eiriktsarpalis, and amended the above proposal - tl;dr don't return the correlation key, and return a tuple instead of IGrouping (though I think the latter can be discussed).