feat: FlatList.Parallel module with the vocabulary of the FSharp.Core Array.Parallel module

[xperiandri]

Proposed Changes

Adds the nested module FlatList.Parallel of ADR 0001 D11 (#23). #26 is merged, and so is #40, which split Helper.fs into root modules and moved InternalsVisibleTo into the project file, as the review of this pull request asked.

• A nested [<RequireQualifiedAccess>] module Parallel at the end of the root module FlatList in FlatList.fsi/.fs, as Array.Parallel lives inside array.fs: the 32 functions of Array.Parallel except the three sortInPlace* (average, averageBy, choose, collect, exists, filter, forall, groupBy, init, iter, iteri, map, mapi, max, maxBy, min, minBy, partition, partitionWith, reduce, reduceBy, sort, sortBy, sortByDescending, sortDescending, sortWith, sum, sumBy, tryFind, tryFindIndex, tryPick, zip). The module has its own category banners, the compiled names of Array.Parallel and full XML documentation.
• Shapes as in the main module: tryFind, tryFindIndex and tryPick return voption, choose and tryPick take voption choosers, and zip, groupBy, partition and partitionWith return struct tuples. Nested Parallel modules in the root modules Option.FlatList and Tuple.FlatList repeat them with options and reference tuples.
• Most functions unwrap the array without a copy and call Array.Parallel. Six functions use new shared algorithms in the file Helper/ParallelArrays.fs (the root module ParallelArrays, after Arrays.fs in the project file), so that nothing is allocated per element:
  • choose maps to value options in parallel and compacts them sequentially;
  • tryFind and tryFindIndex run the same parallel loop with Break as FSharp.Core;
  • tryPick keeps the value of the lowest index under a lock;
  • zip uses the chunks of Array.Parallel.zip, computed without Int32 overflow for every array length;
  • collect maps in parallel and concatenates through a builder.
• groupBy computes the keys in parallel and groups them sequentially through ToLookup, so null keys work. Keys compare in F# structural equality, except float and float32 keys, which compare with GenericEqualityER as in Array.Parallel.groupBy, so all NaN keys are in one group. The order of its result is unspecified, as for Array.Parallel.groupBy.
• The tests reach the internal chunk bounds of the parallel loops through the InternalsVisibleTo item that the base pull request puts into the project file of the library (this pull request has no assembly attribute in a source file any more), so the bounds are tested for arrays that do not fit into the memory of a test run.

Tests (2760 per target framework, 313 of them for Parallel): every function is compared with its sequential FlatList counterpart on the contract inputs and on 10 000 shuffled elements; groupBy, iter and iteri are compared after sorting, and reduceBy with Array.Parallel.reduceBy. Exceptions for empty, mismatched and default inputs are compared with Array.Parallel. Every case is a data row: the inputs are the cases of a ParallelInput union (Empty, Singleton, Several, Large, whose elements the test builds, so that a row prints a short name) and the functions are the cases of predicate unions, so each of the 312 cases of the former loops runs as a test of its own. The Option and Tuple tests prove that the nested overrides shadow the default functions. The test classes carry the Parallel category (D8).

Types of changes

What types of changes does your code introduce to FSharp.Collections.Immutable?
Put an x in the boxes that apply

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.

• Build and tests pass locally
• I have added tests that prove my fix is effective or that my feature works (if appropriate)
• I have added necessary documentation (if appropriate)

Further comments

Deliberate details, each documented on the function:

• iter and iteri are in the Folding category, as in the main module; ADR Appendix A lists the Parallel row under Transformation.
• init with a negative count throws OverflowException, exactly as Array.Parallel.init does (the sequential init throws ArgumentException).
• sum and sumBy throw ArgumentNullException for a default flat list, as D6 requires. Array.Parallel throws NullReferenceException for a null array, although its documentation names ArgumentNullException.
• collect throws ArgumentNullException for a default flat list from the mapping, as the sequential collect does. Array.Parallel.collect dereferences a null result.
• maxBy and minBy return the last of several elements with the greatest or smallest key, as Array.Parallel does.
• Array.Parallel.groupBy throws AggregateException for other keys that contain NaN, such as tuples: its second pass cannot find the key that its first pass added. Here such keys compare in F# structural equality, so each NaN is a group of its own, as in Array.groupBy.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Chunk arithmetic can overflow for large zip inputs, and NaN grouping differs from Array.Parallel.

2 open issues

• Ceiling division overflows for large arrays · New
• groupBy uses inconsistent NaN key equality · New

What changed in this PR

Adds FlatList.Parallel, implementing ADR 0001’s parallel collection API alongside the sequential FlatList module.

Changes:

• Adds 32 parallel functions with documented signatures.
• Provides shared algorithms and Option/Tuple overrides.
• Adds behavior, exception, and namespace-resolution tests.

File	Description
tests/​FSharp.Collections.Immutable.Tests/​FSharp.Collections.Immutable.Tests.fsproj	Registers parallel tests.
tests/​FSharp.Collections.Immutable.Tests/​FlatList/​FlatListParallelTupleTests.fs	Tests Tuple overrides.
tests/​FSharp.Collections.Immutable.Tests/​FlatList/​FlatListParallelTests.fs	Tests parallel behavior and exceptions.
tests/​FSharp.Collections.Immutable.Tests/​FlatList/​FlatListParallelOptionTests.fs	Tests Option overrides.
src/​FSharp.Collections.Immutable/​Helper.fs	Adds shared parallel algorithms.
src/​FSharp.Collections.Immutable/​FlatList/​FlatListTuple.fsi	Documents parallel Tuple signatures.
src/​FSharp.Collections.Immutable/​FlatList/​FlatListTuple.fs	Implements parallel Tuple overrides.
src/​FSharp.Collections.Immutable/​FlatList/​FlatListOption.fsi	Documents parallel Option signatures.
src/​FSharp.Collections.Immutable/​FlatList/​FlatListOption.fs	Implements parallel Option overrides.
src/​FSharp.Collections.Immutable/​FlatList/​FlatList.fsi	Defines the documented parallel API.
src/​FSharp.Collections.Immutable/​FlatList/​FlatList.fs	Implements the parallel module.
CHANGELOG.md	Records the new API.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

Static review found no unresolved blockers, and the prior overflow and NaN defects have fixes with regression coverage; builds and tests were not run.

No open issues 🎉

2 resolved since last review

• groupBy uses inconsistent NaN key equality
• Ceiling division overflows for large arrays

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The custom concurrent algorithms warrant human validation across both target frameworks; builds and tests were not run during this review.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

No blocking defects were identified, but the custom concurrent algorithms need final human review and runtime validation.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

Static review found no unresolved blocking issues, and previously reported defects have regression coverage; builds and tests were not run.

No open issues 🎉

_{Review effort: Balanced}