[xperiandri]

Problem

Cosmos DB compares text by character code. System.Text.Json writes a TimeSpan as text, for example "2.00:00:00". Thus a query with ORDER BY or > on a TimeSpan field returns the wrong result:

• "2.00:00:00" sorts after "10.00:00:00".
• "23:00:00" sorts after both.

System.Text.Json has no option for another format. JsonSerializerOptions has no setting for it, and FSharp.SystemTextJson has no converter for TimeSpan.

Change

• Add TimeSpanTicksConverter (src/Cosmos/JsonConverters.fs). It writes the number of ticks as a JSON number. One tick is 100 nanoseconds. Cosmos DB sorts and compares a number in time order.
• The converter reads the old text form too. Thus a container with old documents stays readable.
• The converter handles Nullable<TimeSpan> and a TimeSpan as the key of a dictionary.
• Add the how-to page How To store a duration and an entry in CHANGELOG.md.
• Add Emulator.createClientWithJson to the test infrastructure. It creates a client with System.Text.Json options.

The converter is for System.Text.Json. The library has no other dependency for it, because net10.0 includes System.Text.Json.

Tests

• 27 unit tests: the written number, a round trip of the smallest and the largest TimeSpan, the old text form (also the text that the default converter writes), values that must fail, Nullable<TimeSpan>, dictionary keys, and a record.
• 4 tests on the emulator. DurationsScenario writes the same six durations two times, through each serializer into a partition of its own, and the tests read them. As the rule for scenarios says, the test class refers to DurationsScenario.TestApplicationFactory through the namespace and opens the namespace for the other types of the scenario. The scenario inherits from OperationTestApplicationFactory (test: let the fixture create the containers of a scenario #71), so the fixture creates the container:
  • ORDER BY returns the durations in time order with the converter.
  • A filter with a TimeSpan parameter keeps the right durations. The client writes the parameter with the converter.
  • The documents with the old text form are read with the converter.
  • Negative control: with the default converter, ORDER BY returns the order of the text. This is why the converter exists.

On the Windows emulator (Microsoft.Azure.Cosmos 3.62.0), the 31 TimeSpan tests and the 14 tests of the categories "Read", "Read many" and "Iteration extensions" pass. Before the scenario, the whole suite passed (233 tests). The Release and Debug builds add no warning, and the strict documentation build passes.

Notes for the reviewer

• I chose ticks, not seconds or milliseconds. Ticks are exact for each TimeSpan. The unit is not in the document, so a query written by hand must use ticks. The how-to page says so.
• Cosmos DB defines a JSON number as a 64-bit floating-point number, which holds each whole number up to 2^53 exactly. This is about 28 years of ticks. On the emulator, an integer above 2^53 stayed exact.
• DateTime and DateTimeOffset have a related problem: System.Text.Json drops the trailing zeros of the fraction, so ...:00Z sorts after ...:00.5Z. This PR does not change them. A converter for them fits in the same file.
• The query translator of ADR 0001 can recognize this converter and treat the field as a number.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

No blocking defects were identified; remaining feedback concerns minor coding conventions.

0 open findings

What changed in this PR

Adds an opt-in System.Text.Json converter that stores durations as numeric ticks for Cosmos DB sorting and filtering, while preserving reads of legacy text values.

Changes:

• Adds tick serialization, including nullable values and dictionary keys.
• Adds unit and emulator coverage with configurable JSON clients.
• Documents setup, migration, and precision limits.

File	Description
tests/​Cosmos.Tests/​TimeSpanTicksConverterTests.fs	Tests serialization and supported inputs.
tests/​Cosmos.Tests/​TimeSpanTicksConverterIntegrationTests.fs	Tests sorting, filtering, and legacy reads.
tests/​Cosmos.Tests/​TestCategories.fs	Adds converter test categories.
tests/​Cosmos.Tests/​FSharp.Azure.Cosmos.Tests.fsproj	Includes both test files.
tests/​Cosmos.Tests.Infrastructure/​Emulator.fs	Adds configurable JSON clients.
src/​Cosmos/​JsonConverters.fs	Implements the ticks converter.
src/​Cosmos/​FSharp.Azure.Cosmos.fsproj	Includes the converter.
docsSrc/​How_Tos/​Store_Durations.md	Explains usage and limitations.
CHANGELOG.md	Announces the converter.

🧠 Review effort: Balanced

---

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

[xperiandri]

If you always seed the same data why don't you derive from OperationTestBase<> with scenario?

[xperiandri]

About the review comment "derive from OperationTestBase<> with scenario": done in 67082c4 (folded into the single commit).

• tests/Cosmos.Tests/Scenarios/DurationsScenario.fs has the shape of the Ecierge scenarios: a [<Struct>] TestData record, the data created in the constructor of TestApplicationFactory, and SeedDataAsync that only writes the data.
• The scenario writes the same six durations two times: through TimeSpanTicksConverter into the partition ticks, and through the default converter into the partition text.
• TimeSpanTicksConverterIntegrationTests derives from OperationTestBase<TestApplicationFactory>, and each test reads its values with let { … } = this.Application.TestData.
• The test of the old text form now reads all six text documents with the converter, not one document.

The 31 TimeSpan tests (27 unit, 4 emulator) pass on the Windows emulator.