FSharp.Control.TaskSeq 0.4.0-alpha.1

This is a prerelease version of FSharp.Control.TaskSeq.
There is a newer version of this package available.
See the version list below for details.
dotnet add package FSharp.Control.TaskSeq --version 0.4.0-alpha.1
NuGet\Install-Package FSharp.Control.TaskSeq -Version 0.4.0-alpha.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="FSharp.Control.TaskSeq" Version="0.4.0-alpha.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add FSharp.Control.TaskSeq --version 0.4.0-alpha.1
#r "nuget: FSharp.Control.TaskSeq, 0.4.0-alpha.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install FSharp.Control.TaskSeq as a Cake Addin
#addin nuget:?package=FSharp.Control.TaskSeq&version=0.4.0-alpha.1&prerelease

// Install FSharp.Control.TaskSeq as a Cake Tool
#tool nuget:?package=FSharp.Control.TaskSeq&version=0.4.0-alpha.1&prerelease

TaskSeq

An implementation of IAsyncEnumerable<'T> as a computation expression: taskSeq { ... } with an accompanying TaskSeq module.


Table of contents


Overview

The IAsyncEnumerable interface was added to .NET in .NET Core 3.0 and is part of .NET Standard 2.1. The main use-case was for iterative asynchronous enumeration over some resource. For instance, an event stream or a REST API interface with pagination, asynchronous reading over a list of files and accumulating the results, where each action can be modeled as a MoveNextAsync call on the IAsyncEnumerator<'T> given by a call to GetAsyncEnumerator().

Since the introduction of task in F# the call for a native implementation of task sequences has grown, in particular because proper iterating over an IAsyncEnumerable has proven challenging, especially if one wants to avoid mutable variables. This library is an answer to that call and implements the same resumable state machine approach with taskSeq.

Module functions

As with seq and Seq, this library comes with a bunch of well-known collection functions, like TaskSeq.empty, isEmpty or TaskSeq.map, iter, collect, fold and TaskSeq.find, pick, choose, filter. Where applicable, these come with async variants, like TaskSeq.mapAsync iterAsync, collectAsync, foldAsync and TaskSeq.findAsync, pickAsync, chooseAsync, filterAsync, which allows the applied function to be asynchronous.

See below for a full list of currently implemented functions and their variants.

taskSeq computation expressions

The taskSeq computation expression can be used just like using seq. On top of that, it adds support for working with tasks through let! and looping over a normal or asynchronous sequence (one that implements IAsyncEnumerable<'T>'). You can use yield! and yield and there's support for use and use!, try-with and try-finally and while loops within the task sequence expression.

Examples

open System.IO
open FSharp.Control

// singleton is fine
let helloTs = taskSeq { yield "Hello, World!" }

// cold-started, that is, delay-executed
let f() = task {
    // using toList forces execution of whole sequence
    let! hello = TaskSeq.toList helloTs  // toList returns a Task<'T list>
    return List.head hello 
}

// can be mixed with normal sequences
let oneToTen = taskSeq { yield! [1..10] }

// can be used with F#'s task and async in a for-loop
let f() = task { for x in oneToTen do printfn "Number %i" x }
let g() = async { for x in oneToTen do printfn "Number %i" x }

// returns a delayed sequence of IAsyncEnumerable<string>
let allFilesAsLines() = taskSeq {
    let files = Directory.EnumerateFiles(@"c:\temp")
    for file in files do
        // await
        let! contents = File.ReadAllLinesAsync file
        // return all lines
        yield! contents
}

let write file = 
    allFilesAsLines()
    
    // synchronous map function on asynchronous task sequence
    |> TaskSeq.map (fun x -> x.Replace("a", "b"))

    // asynchronous map
    |> TaskSeq.mapAsync (fun x -> task { return "hello: " + x })
    
    // asynchronous iter
    |> TaskSeq.iterAsync (fun data -> File.WriteAllTextAsync(fileName, data))


// infinite sequence
let feedFromTwitter user pwd = taskSeq {
    do! loginToTwitterAsync(user, pwd)
    while true do
       let! message = getNextNextTwitterMessageAsync()
       yield message
}

TaskSeq module functions

We are working hard on getting a full set of module functions on TaskSeq that can be used with IAsyncEnumerable sequences. Our guide is the set of F# Seq functions in F# Core and, where applicable, the functions provided from AsyncSeq. Each implemented function is documented through XML doc comments to provide the necessary context-sensitive help.

The following is the progress report:

Done Seq TaskSeq Variants Remarks
allPairs allPairs note #1
#81 append append
#81 appendSeq
#81 prependSeq
average average
averageBy averageBy averageByAsync
cache cache note #1
#67 cast cast
#67 box
#67 unbox
#23 choose choose chooseAsync
chunkBySize chunkBySize
#11 collect collect collectAsync
#11 collectSeq collectSeqAsync
compareWith compareWith compareWithAsync
#69 concat concat
#70 contains contains
#82 delay delay
distinct distinct
distinctBy dictinctBy distinctByAsync
#2 empty empty
#23 exactlyOne exactlyOne
#83 except except
#83 exceptOfSeq
#70 exists exists existsAsync
exists2 exists2
#23 filter filter filterAsync
#23 find find findAsync
🚫 findBack note #2
#68 findIndex findIndex findIndexAsync
🚫 findIndexBack n/a n/a note #2
#2 fold fold foldAsync
fold2 fold2 fold2Async
🚫 foldBack note #2
🚫 foldBack2 note #2
forall forall forallAsync
forall2 forall2 forall2Async
groupBy groupBy groupByAsync note #1
#23 head head
#68 indexed indexed
#69 init init initAsync
#69 initInfinite initInfinite initInfiniteAsync
insertAt insertAt
insertManyAt insertManyAt
#23 isEmpty isEmpty
#23 item item
#2 iter iter iterAsync
iter2 iter2 iter2Async
#2 iteri iteri iteriAsync
iteri2 iteri2 iteri2Async
#23 last last
#53 length length
#53 lengthBy lengthByAsync
#2 map map mapAsync
map2 map2 map2Async
map3 map3 map3Async
mapFold mapFold mapFoldAsync
🚫 mapFoldBack note #2
#2 mapi mapi mapiAsync
mapi2 mapi2 mapi2Async
max max
maxBy maxBy maxByAsync
min min
minBy minBy minByAsync
#2 ofArray ofArray
#2 ofAsyncArray
#2 ofAsyncList
#2 ofAsyncSeq
#2 ofList ofList
#2 ofTaskList
#2 ofResizeArray
#2 ofSeq
#2 ofTaskArray
#2 ofTaskList
#2 ofTaskSeq
pairwise pairwise
permute permute permuteAsync
#23 pick pick pickAsync
🚫 readOnly note #3
reduce reduce reduceAsync
🚫 reduceBack note #2
removeAt removeAt
removeManyAt removeManyAt
replicate replicate
rev note #1
scan scan scanAsync
🚫 scanBack note #2
#90 singleton singleton
skip skip
skipWhile skipWhile skipWhileAsync
sort note #1
sortBy note #1
sortByAscending note #1
sortByDescending note #1
sortWith note #1
splitInto splitInto
sum sum
sumBy sumBy sumByAsync
#76 tail tail
take take
takeWhile takeWhile takeWhileAsync
#2 toArray toArray toArrayAsync
#2 toIList toIListAsync
#2 toList toList toListAsync
#2 toResizeArray toResizeArrayAsync
#2 toSeq toSeqAsync
[…]
transpose note #1
truncate truncate
#23 tryExactlyOne tryExactlyOne tryExactlyOneAsync
#23 tryFind tryFind tryFindAsync
🚫 tryFindBack note #2
#68 tryFindIndex tryFindIndex tryFindIndexAsync
🚫 tryFindIndexBack note #2
#23 tryHead tryHead
#23 tryItem tryItem
#23 tryLast tryLast
#23 tryPick tryPick tryPickAsync
#76 tryTail
unfold unfold unfoldAsync
updateAt updateAt
where where whereAsync
windowed windowed
#2 zip zip
zip3 zip3
zip4
Note 1

These functions require a form of pre-materializing through TaskSeq.cache, similar to the approach taken in the corresponding Seq functions. It doesn't make much sense to have a cached async sequence. However, AsyncSeq does implement these, so we'll probably do so eventually as well.

Note 2

Because of the async nature of TaskSeq sequences, iterating from the back would be bad practice. Instead, materialize the sequence to a list or array and then apply the xxxBack iterators.

Note 3

The motivation for readOnly in Seq is that a cast from a mutable array or list to a seq<_> is valid and can be cast back, leading to a mutable sequence. Since TaskSeq doesn't implement IEnumerable<_>, such casts are not possible.

More information

Further reading IAsyncEnumerable

  • A good C#-based introduction can be found in this blog.
  • An MSDN article written shortly after it was introduced.
  • Converting a seq to an IAsyncEnumerable demo gist as an example, though TaskSeq contains many more utility functions and uses a slightly different approach.
  • If you're looking for using IAsyncEnumerable with async and not task, the excellent AsyncSeq library should be used. While TaskSeq is intended to consume async just like task does, it won't create an AsyncSeq type (at least not yet). If you want classic Async and parallelism, you should get this library instead.

Further reading on resumable state machines

Further reading on computation expressions

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.1 is compatible. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (8)

Showing the top 5 NuGet packages that depend on FSharp.Control.TaskSeq:

Package Downloads
Equinox.CosmosStore

Efficient event sourced decisions and data

Equinox.EventStore

Efficient event sourced decisions and data

Propulsion.Feed

Efficient event streaming pipelines

Equinox.DynamoStore

Efficient event sourced decisions and data

Equinox.SqlStreamStore

Efficient event sourced decisions and data

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.4.0 1,943 3/17/2024
0.4.0-alpha.1 31,325 6/5/2023
0.3.0 99,332 11/28/2022
0.2.2 1,541 11/10/2022
0.2.1 656 11/10/2022
0.2.0 339 11/9/2022
0.1.1 325 11/9/2022
0.1.0 388 11/9/2022

Release notes:
0.4.x (unreleased)
   - fix documentation

0.4.0-alpha.1
   - fixes not calling Dispose for 'use!', 'use', or `finally` blocks #157 (by @bartelink)
   - BREAKING CHANGE: null args now raise ArgumentNullException instead of NullReferenceException, #127
   - adds `let!` and `do!` support for F#'s Async<'T>, #79, #114
   - adds TaskSeq.takeWhile, takeWhileAsync, takeWhileInclusive, takeWhileInclusiveAsync, #126 (by @bartelink)
   - adds AsyncSeq vs TaskSeq comparison chart, #131
   - removes release-notes.txt from file dependencies, but keep in the package, #138
   
0.3.0
   - internal renames, improved doc comments, signature files for complex types, hide internal-only types, fixes #112.
   - adds support for static TaskLike, allowing the same let! and do! overloads that F# task supports, fixes #110.
   - implements 'do!' for non-generic Task like with Task.Delay, fixes #43.
   - adds support for 'for .. in ..' with task sequences in F# tasks and async, #75, #93 and #99 (with help from @theangrybyrd).
   - adds TaskSeq.singleton, #90 (by @gusty).
   - fixes overload resolution bug with 'use' and 'use!', #97 (thanks @peterfaria).
   - improves TaskSeq.empty by not relying on resumable state, #89 (by @gusty).
   - does not throw exceptions anymore for unequal lengths in TaskSeq.zip, fixes #32.

0.2.2
   - removes TaskSeq.toSeqCachedAsync, which was incorrectly named. Use toSeq or toListAsync instead.
   - renames TaskSeq.toSeqCached to TaskSeq.toSeq, which was its actual operational behavior.

0.2.1
   - fixes an issue with ValueTask on completed iterations.
   - adds `TaskSeq.except` and `TaskSeq.exceptOfSeq` async set operations.

0.2
   - moved from NET 6.0, to NetStandard 2.1 for greater compatibility, no functional changes.
   - move to minimally necessary FSharp.Core version: 6.0.2.
   - updated readme with progress overview, corrected meta info, added release notes.

0.1.1
   - updated meta info in nuget package and added readme.

0.1
   - initial release
   - implements taskSeq CE using resumable state machines
       - with support for: yield, yield!, let, let!, while, for, try-with, try-finally, use, use!
       - and: tasks and valuetasks
   - adds toXXX / ofXXX functions
   - adds map/mapi/fold/iter/iteri/collect etc with async variants
   - adds find/pick/choose/filter etc with async variants and 'try' variants
   - adds cast/concat/append/prepend/delay/exactlyOne
   - adds empty/isEmpty
   - adds findIndex/indexed/init/initInfinite
   - adds head/last/tryHead/tryLast/tail/tryTail
   - adds zip/length