TaskSeq alias

[bartelink]

/// <summary>
/// Represents a task sequence and is the output of using the <paramref name="taskSeq{...}" />
/// computation expression from this library. It is an alias for <see cref="T:System.IAsyncEnumerable&lt;_>" />.
/// </summary>
type TaskSeq<'T> = IAsyncEnumerable<'T>

https://github.com/fsprojects/FSharp.Control.TaskSeq/blob/main/src/FSharp.Control.TaskSeq/TaskSeqBuilder.fsi#L37-L41

This leaks into the FSharp.Control public interface.

Pros:

• If you have an open FSharp.Control [as a result of using a TaskSeq.* operation] you get it for free
• FSharp.Control is a shorter name than System.Collections.Generic (there's a typo in the xmdoc)

Cons:

• if you want to use it to pin a type, you need to open it
• it stops people from considering the point that it's fully interoperable with C# and simply a normal framework thing. You could drop it and people would have less mystical app code.

---

@abelbraaksma Putting this here as I'd be interested to hear your thoughts/considerations on the tradeoffs...

I intuitively used TaskSeq<'T> in code as the xmldoc for the project as a whole uses it, but then did a double take when reviewing my library's API, converting it the raw types.

My initial thought was: this needs to go; it's an implementation detail, and gets people in the wrong mindset, surely retaining it in 0.4.0 was an oversight?

My current thought is leaning toward: actually, it's terse, self-consistent with F# stuff in general, and that I'll probably switch my API back to leaning on the alias wherever possible; less chars, one less open

[abelbraaksma]

Intriguing questions!

This leaks into the FSharp.Control public interface.

Not a leak. Deliberate exposure 😄 and helping people getting it right easily.

You could drop it and people would have less mystical app code.

The reason we use an alias is the same as why aliases are used in F#: as a simplified, in-scope shortcut. It mimics the way Seq<_> aliases IEnumerable<_> etc.

but then did a double take when reviewing jet/equinox#450, converting it the raw types.

They are both raw types. It's just an F# alias. After compiling, the difference is gone. C# users will never see the aliases, even if you would have used them.

My initial thought was: this needs to go; it's an implementation detail

No, it is not an implementation detail. It is a deliberate choice and follows the rules of F# library design, where you create a type (or alias) and a corresponding module with the operations you support on that type.

It helps with ease of discovery. People do not need to know the implementation detail that IAsyncEnumerable is in some far away hidden System namespace. Simple: people download the library, open the namespace, and can do everything they need to, because the alias brings the type in scope.

It is highly recommended to use TaskSeq<_> instead of the more verbose IAsyncEnumerable. That way, your code has parity between the returned types and the operations it does on it (using TaskSeq.xxx functions). Similarly, it maps better with the taskSeq CE, again following naming conventions and lib design principles.

The thought is simple: if you use taskSeq, you can use TaskSeq.xxx functions on it. If your function receives a type TaskSeq<_>, it can use TaskSeq.xxx operations, and be used in task { for ... in .. do }, and taskSeq {...} and async {...} expressions.

Using IAsyncEnumerable instead, would require to use long, unintuitive names for the module and CE, like IAsyncEnumerable.mapAsync simply doesn't have the X-factor as TaskSeq.mapAsync has.

Furthermore, it is uncommon to write library functions modules that have the name of an interface. So we'd need to use AsyncEnumerable.mapAsync, which is wrong for many other reasons.

Bottom line: this is was a very conscious and deliberate decision, following long-standing practices and guidelines for F# library design.

[abelbraaksma]

Other thoughts are orthogonality with existing, widely used libraries. There's async, module Async and type Async<_>. Then came CE asyncSeq module AsyncSeq and type AsyncSeq<_>. Next up was task CE with module Task and type Task<_> (no alias). Internally (in F# Core test code) an implementation of taskSeq CE, TaskSeq module and TaskSeq<_> type.

I used the same approach, and copied over the work already done in F# Core.

related discussion: #188

[bartelink]

Thanks for the complete and thoughtful response. It all seems so obvious and rational when you put it that way - no further questions :)

As a complete non-sequiter, thanks for all the work you've done; I've recently gotten to use it more deeply in app code (and in jet/equinox#450) - it's extremely nice to have a key part of your array of tools be entirely trustworthy; to know that something is so thoroughly tested makes reasoning about problems take less energy, and the overall experience so much more pleasurable.