refactor: return voption and struct tuples from the collection functions

[xperiandri]

Proposed Changes

The repository prefers voption and struct tuples, but FSharp.Core's collection functions that look an element up return an option, and zip returns reference tuples. Every call then either allocates or needs a conversion at the call site. This was asked for in the review of #43 (helpers that return voption, zip over Enumerable.Zip).

src/Shared/ValueCollections.fs defines functions with the names and the meaning of FSharp.Core's, for Seq, List and Array:

• tryHead, tryLast, tryItem, tryExactlyOne, tryFind, tryFindBack, tryFindIndex, tryFindIndexBack return a voption;
• tryPick returns a voption and takes a chooser that returns one;
• zip returns struct tuples. Seq.zip is Enumerable.Zip; Array.zip and List.zip still reject collections of different lengths, as FSharp.Core's do.

They shadow FSharp.Core's functions: Seq.tryHead now means this one. A function that only FSharp.Core has, such as Seq.map, resolves to FSharp.Core as before, and a shadowed one stays reachable by its full name (Microsoft.FSharp.Collections.Seq.tryHead).

How it reaches the code. The root Directory.Build.props adds the file as the first Compile item of every F# project under src and tests, so each project gets its own internal copy and a new project gets it without doing anything. The module is FSharp.Azure.Cosmos.ValueCollections and marked AutoOpen:

• in the code of the namespace FSharp.Azure.Cosmos, which includes modules declared as module FSharp.Azure.Cosmos.X, the shadows are in effect without an open;
• any other file gets them with open FSharp.Azure.Cosmos, which nearly every file of the library and of its tests has anyway;
• that includes a file in a child namespace such as FSharp.Azure.Cosmos.Tests: a child namespace does not open the modules of its parent (tried out);
• a file that does not open the namespace keeps FSharp.Core's functions.

The build project is left out: its scripts were generated against FSharp.Core's functions.

The two places on main that used such a function follow: the first item of a feed page in Read.fs and a zip in the ExistsAsync concurrency test.

Change after the review

The module was in the global namespace, so that the shadows were in effect in every file without an open. As asked in the review, it is in the namespace FSharp.Azure.Cosmos now. The one file here that needed the open for it is the test of the shadows; the other two places that use them are inside the namespace or open it already. The branch is also rebased onto the current main.

Types of changes

• 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)

Internal refactoring; the public API of the package is unchanged.

Checklist

• 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

• ValueCollectionsTests (5 tests, category ValueCollections, no emulator) runs every shadow and the FSharp.Core function it hides over the same inputs – empty, one element, repeated elements, a longer run; indexes before, inside and past the collection – and asserts equal answers.
• Windows emulator: Debug 190/190 and Release 190/190. Fantomas is clean, and the documentation builds with --strict.
• Not shadowed: choose and pick, whose choosers return an option as well, and Map.tryFind. They are not "try" functions of the three modules that the review named; say so if they should follow.
• Of the open pull requests only test: add a Hedgehog adapter for MSTest property tests #43 uses these functions beyond the two places above; it is built on this branch, so this one has to be merged first.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

The helpers preserve expected semantics, affected usages are updated, and the new behavior is comprehensively tested.

0 open findings

What changed in this PR

Introduces repository-wide collection helpers that return voption and struct tuples while preserving FSharp.Core behavior.

Changes:

• Adds shadowing Seq, List, and Array helpers.
• Updates affected call sites for new result types.
• Adds comprehensive emulator-free tests and project guidance.

File	Description
.github/​copilot-instructions.md	Documents the shared helpers and conventions.
Directory.Build.props	Includes helpers in applicable F# projects.
src/​Shared/​ValueCollections.fs	Implements collection shadows.
src/​Cosmos/​Read.fs	Handles the new voption result.
tests/​Cosmos.Tests/​FSharp.Azure.Cosmos.Tests.fsproj	Includes the new tests.
tests/​Cosmos.Tests/​ReadExtensionsTests.fs	Updates struct-tuple pattern matching.
tests/​Cosmos.Tests/​TestCategories.fs	Adds the test category attribute.
tests/​Cosmos.Tests/​ValueCollectionsTests.fs	Verifies behavior against FSharp.Core.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[xperiandri]

Should we stack it on top of Hedgehog and perform property testing? Or does not make sense?

[xperiandri]

Should we stack it on top of Hedgehog and perform property testing? Or does not make sense?

It makes sense, and it is done in #50. Stacking this pull request on the Hedgehog one is not possible, though, so the property tests come as a third step.

Why it makes sense. Every function here hides the FSharp.Core function of the same name and must mean the same. That gives each one an oracle: another implementation that knows the expected answer for any input. A test can then run both on generated input and compare, with no expected values written by hand. That is the case property tests suit best.

Why not by stacking. The dependency goes the other way: the adapter of #43 is written with these functions (its review asked for the repository's conventions in the ported code), so #43 is built on this branch. The order is #47, then #43, then #50.

What #50 does. It replaces the three test methods of this pull request that compare the shadows with FSharp.Core on five hand-picked arrays by four methods marked [<Property>]: first, last and only element; element at an index; the five search functions; zip. Each compares Seq, List and Array on the same generated input, 100 inputs per run.

Does it find more? I planted a defect that the hand-picked arrays do not reach: List.tryLast returning the element before the last one when that element is 3. The tests of this pull request pass with it, 5 of 5. The property fails after 24 generated cases and reports the smallest failing input, items = [|0; 3; 0|]. The defect was reverted afterwards; #50 describes the two other defects tried and what the generators produce.

Nothing changes in this pull request: its hand-picked tests stay until #50 replaces them.