Merge pull request #3392 from obsidian-tasks-group/prevent-floating-point-groupnames

fix: Stable `group by function task.urgency` order

Author: claremacrae

docs/Queries/Grouping.md

@@ -663,6 +663,15 @@ group by function task.urgency.toFixed(3)
 
 - Show the urgency to 3 decimal places, unlike the built-in "group by urgency" which uses 2.
 
+```javascript
+group by function task.urgency
+```
+
+- Show non-integer urgency values to 5 decimal places, and integer ones to 0 decimal places.
+- Sorting of groups by name has been found to be unreliable with varying numbers of decimal places.
+- So to ensure consistent sorting, Tasks will round non-integer numbers to a fixed 5 decimal places, returning the value as a string.
+- This still sorts consistently even when some of the group's values are integers.
+
 <!-- placeholder to force blank line after included text --><!-- endInclude -->
 
 ### Recurrence

docs/Scripting/Custom Grouping.md

@@ -13,6 +13,7 @@ publish: true
 
 - Define your own custom task groups, using JavaScript expressions such as:
   - `group by function task.urgency.toFixed(3)`
+  - See [[#Number property examples]] below for how floating point numbers are treated, if the precision (number of decimal places) is not specified.
 - There are loads of examples in [[Grouping]].
   - Search for `group by function` in that file.
 - Find all the **supported tasks properties** in [[Task Properties]] and [[Quick Reference]].
@@ -193,6 +194,15 @@ group by function task.urgency.toFixed(3)
 
 - Show the urgency to 3 decimal places, unlike the built-in "group by urgency" which uses 2.
 
+```javascript
+group by function task.urgency
+```
+
+- Show non-integer urgency values to 5 decimal places, and integer ones to 0 decimal places.
+- Sorting of groups by name has been found to be unreliable with varying numbers of decimal places.
+- So to ensure consistent sorting, Tasks will round non-integer numbers to a fixed 5 decimal places, returning the value as a string.
+- This still sorts consistently even when some of the group's values are integers.
+
 <!-- placeholder to force blank line after included text --><!-- endInclude -->
 
 ### File property examples

src/Query/Filter/FunctionField.ts

@@ -283,6 +283,14 @@ export function groupByFunction(task: Task, arg: GroupingArg, queryContext?: Que
             return [];
         }
 
+        if (typeof result === 'number' && !Number.isInteger(result)) {
+            // Guard against #3371: order of groups, when grouping by "function task.urgency" without specifying precision, is confusing.
+            // Sorting has been found to be unreliable with varying numbers of decimal places.
+            // So to ensure consistent sorting, we round the value to a fixed number of decimals and return it as a string.
+            // This still sorts consistently even when some of the group's values are integers.
+            return [result.toFixed(5)];
+        }
+
         // If there was an error in the expression, like it referred to
         // an unknown task field, result will be undefined, and the call
         // on undefined.toString() will give an exception and a useful error

tests/Query/Filter/FunctionField.test.ts

@@ -522,7 +522,7 @@ describe('FunctionField - grouping return types', () => {
         ['1', ['1']],
         ['0', ['0']],
         ['0 || "No value"', ['No value']],
-        ['1.0765456', ['1.0765456']],
+        ['1.0765456', ['1.07655']],
         ['1.0765456.toFixed(3)', ['1.077']],
         ['["heading1", "heading2"]', ['heading1', 'heading2']], // return two headings, indicating that this task should be displayed twice, once in each heading
         ['[1, 2]', ['1', '2']], // return two headings, that need to be converted to strings

tests/Query/Group/TaskGroups.test.ts

@@ -13,16 +13,23 @@ import { StatusTypeField } from '../../../src/Query/Filter/StatusTypeField';
 import { HappensDateField } from '../../../src/Query/Filter/HappensDateField';
 import { DueDateField } from '../../../src/Query/Filter/DueDateField';
 import { SearchInfo } from '../../../src/Query/SearchInfo';
-import { fromLine } from '../../TestingTools/TestHelpers';
+import { fromLine, fromLines } from '../../TestingTools/TestHelpers';
 import { TaskBuilder } from '../../TestingTools/TaskBuilder';
 import { TasksFile } from '../../../src/Scripting/TasksFile';
+import { FunctionField } from '../../../src/Query/Filter/FunctionField';
+import type { TaskGroup } from '../../../src/Query/Group/TaskGroup';
 
 window.moment = moment;
 
-function makeTasksGroups(grouping: Grouper[], inputs: Task[]): any {
+function makeTasksGroups(grouping: Grouper[], inputs: Task[]): TaskGroups {
     return new TaskGroups(grouping, inputs, SearchInfo.fromAllTasks(inputs));
 }
 
+beforeEach(() => {});
+
+afterEach(() => {
+    jest.useRealTimers();
+});
 describe('Grouping tasks', () => {
     it('groups correctly by path', () => {
         // Arrange
@@ -231,6 +238,31 @@ describe('Grouping tasks', () => {
         `);
     });
 
+    it('sorts raw urgency value groups correctly', () => {
+        jest.useFakeTimers();
+        jest.setSystemTime(new Date('2025-03-07'));
+
+        const lines = [
+            '- [ ] 0 📅 2025-02-28 🔺           ', // urgency: 21
+            '- [ ] 1 📅 2025-03-07 ⏳ 2025-03-07', // urgency: 15.75
+            '- [ ] 2 📅 2025-03-08 ⏳ 2025-03-07', // urgency: 15.292857142857141
+            '- [ ] 3 📅 2025-03-09 ⏳ 2025-03-07', // urgency: 14.835714285714285
+            '- [ ] 4 ⏫  🛫 2025-03-18          ', // urgency: 3
+            '- [ ] 5 🔽                         ', // urgency: 0
+        ];
+        const tasks = fromLines({ lines });
+
+        // See issue https://github.com/obsidian-tasks-group/obsidian-tasks/issues/3371
+        //      order of groups, when grouping by "function task.urgency" without specifying precision, is confusing
+        // There is a problem with the sorting of groups whose floating-point values differ in precision,
+        // when grouping by the raw urgency value
+        const grouping = [new FunctionField().createGrouperFromLine('group by function task.urgency')!];
+
+        const groups: TaskGroups = makeTasksGroups(grouping, tasks);
+        const groupHeadings = groups.groups.map((group: TaskGroup) => group.groups[0]);
+        expect(groupHeadings).toEqual(['0', '3', '14.83571', '15.29286', '15.75000', '21']);
+    });
+
     it('handles tasks matching multiple groups correctly', () => {
         const a = fromLine({
             line: '- [ ] Task 1 #group1',

tests/Scripting/ScriptingReference/CustomGrouping/CustomGroupingExamples.test.other_properties_task.urgency_docs.approved.md

@@ -7,5 +7,14 @@ group by function task.urgency.toFixed(3)
 
 - Show the urgency to 3 decimal places, unlike the built-in "group by urgency" which uses 2.
 
+```javascript
+group by function task.urgency
+```
+
+- Show non-integer urgency values to 5 decimal places, and integer ones to 0 decimal places.
+- Sorting of groups by name has been found to be unreliable with varying numbers of decimal places.
+- So to ensure consistent sorting, Tasks will round non-integer numbers to a fixed 5 decimal places, returning the value as a string.
+- This still sorts consistently even when some of the group's values are integers.
+
 
 <!-- placeholder to force blank line after included text -->

tests/Scripting/ScriptingReference/CustomGrouping/CustomGroupingExamples.test.other_properties_task.urgency_results.approved.txt

@@ -13,3 +13,18 @@ Show the urgency to 3 decimal places, unlike the built-in "group by urgency" whi
 9.000
 ====================================================================================
 
+
+group by function task.urgency
+Show non-integer urgency values to 5 decimal places, and integer ones to 0 decimal places.
+Sorting of groups by name has been found to be unreliable with varying numbers of decimal places.
+So to ensure consistent sorting, Tasks will round non-integer numbers to a fixed 5 decimal places, returning the value as a string.
+This still sorts consistently even when some of the group's values are integers.
+=>
+-1.80000
+0
+1.95000
+3.90000
+6
+9
+====================================================================================
+

tests/Scripting/ScriptingReference/CustomGrouping/CustomGroupingExamples.test.ts

@@ -704,6 +704,13 @@ describe('other properties', () => {
                     'group by function task.urgency.toFixed(3)',
                     'Show the urgency to 3 decimal places, unlike the built-in "group by urgency" which uses 2',
                 ],
+                [
+                    'group by function task.urgency',
+                    'Show non-integer urgency values to 5 decimal places, and integer ones to 0 decimal places',
+                    'Sorting of groups by name has been found to be unreliable with varying numbers of decimal places.',
+                    'So to ensure consistent sorting, Tasks will round non-integer numbers to a fixed 5 decimal places, returning the value as a string.',
+                    "This still sorts consistently even when some of the group's values are integers.",
+                ],
             ],
             SampleTasks.withAllPriorities(),
         ],