feat: Add 'limit groups to <number> tasks' (#1963)

* refactor: add limitTo() and test

* feat: apply limit to the tasks

* feat: adjust total task count after deletion

* refactor: extract TaskGroup.limitTo()

* refactor: rename vars

* feat: parse limit group instruction

* refactor: extract taskGroups to a var

* refactor: limitTo() accepts number or undefined

* feat: explain group limit

* fix: remove tasks only if needed

* feat: apply group limits in queries

* refactor: rename new methods

* fix: recount tasks after the limit has been applied

* refactor: extract calculateTotalTaskCount()

* refactor: clarify calculateTotalTaskCount()

* refactor: remove return value from applyTaskLimit()

* test: additional count test and better wordings

* refactor: move undefined check to Query

* docs: add jsdoc comments

* refactor: reverse if-else statement to catch error

* test: explicit wordings in TaskGroups.test.ts

* test: verify that sorting is applied with group limit

* fix: should not apply group limit if no groups were specified

* docs: add group limit

* refactor: use slice() instead of splice() in TaskGroup.applyTaskLimit()

* test: fix test comment

* docs: better jsdoc of TaskGroups.applyTaskLimit()

* feat: modify 'group' to 'groups' in queries

* docs: update docs to new instruction

Author: ilandikov

docs/Queries/Limiting.md

@@ -4,8 +4,18 @@ publish: true
 
 # Limiting
 
-You can limit the number of tasks to show as query results.
+## Total tasks
+
+You can limit the number of total tasks to show as query results.
 Use the query string `limit to <number> tasks`.
 This will only list the `<number>` first results of the query.
 
 Shorthand is `limit <number>`.
+
+## Tasks per group
+
+You can also limit the max number of tasks in groups if grouping is used. Otherwise this limit is ignored.
+Use the query string `limit groups to <number> tasks`.
+This will only list the `<number>` first tasks in each group from the results of the query.
+
+Shorthand is `limit groups <number>`.

src/Query/Query.ts

@@ -13,6 +13,7 @@ export class Query implements IQuery {
     public source: string;
 
     private _limit: number | undefined = undefined;
+    private _taskGroupLimit: number | undefined = undefined;
     private _layoutOptions: LayoutOptions = new LayoutOptions();
     private _filters: Filter[] = [];
     private _error: string | undefined = undefined;
@@ -24,7 +25,7 @@ export class Query implements IQuery {
     private readonly shortModeRegexp = /^short/;
     private readonly explainQueryRegexp = /^explain/;
 
-    private readonly limitRegexp = /^limit (to )?(\d+)( tasks?)?/;
+    private readonly limitRegexp = /^limit (groups )?(to )?(\d+)( tasks?)?/;
 
     private readonly commentRegexp = /^#.*/;
 
@@ -117,6 +118,14 @@ export class Query implements IQuery {
             result += '.\n';
         }
 
+        if (this._taskGroupLimit !== undefined) {
+            result += `\n\nAt most ${this._taskGroupLimit} task`;
+            if (this._taskGroupLimit !== 1) {
+                result += 's';
+            }
+            result += ' per group.\n';
+        }
+
         const { debugSettings } = getSettings();
         if (debugSettings.ignoreSortInstructions) {
             result +=
@@ -161,7 +170,14 @@ export class Query implements IQuery {
         const { debugSettings } = getSettings();
         const tasksSorted = debugSettings.ignoreSortInstructions ? tasks : Sort.by(this.sorting, tasks);
         const tasksSortedLimited = tasksSorted.slice(0, this.limit);
-        return new TaskGroups(this.grouping, tasksSortedLimited);
+
+        const taskGroups = new TaskGroups(this.grouping, tasksSortedLimited);
+
+        if (this._taskGroupLimit !== undefined) {
+            taskGroups.applyTaskLimit(this._taskGroupLimit);
+        }
+
+        return taskGroups;
     }
 
     private parseHideOptions({ line }: { line: string }): void {
@@ -222,11 +238,18 @@ export class Query implements IQuery {
 
     private parseLimit({ line }: { line: string }): void {
         const limitMatch = line.match(this.limitRegexp);
-        if (limitMatch !== null) {
-            // limitMatch[2] is per regex always digits and therefore parsable.
-            this._limit = Number.parseInt(limitMatch[2], 10);
-        } else {
+        if (limitMatch === null) {
             this._error = 'do not understand query limit';
+            return;
+        }
+
+        // limitMatch[3] is per regex always digits and therefore parsable.
+        const limitFromLine = Number.parseInt(limitMatch[3], 10);
+
+        if (limitMatch[1] !== undefined) {
+            this._taskGroupLimit = limitFromLine;
+        } else {
+            this._limit = limitFromLine;
         }
     }
 

src/Query/TaskGroup.ts

@@ -49,7 +49,7 @@ export class TaskGroup {
      * All the tasks that match the user's filters and that have the
      * group names exactly matching groups().
      */
-    public readonly tasks: Task[];
+    public tasks: Task[];
 
     /**
      * Constructor
@@ -68,6 +68,18 @@ export class TaskGroup {
         }
     }
 
+    /**
+     * Limits {@link tasks} array to a certain number. Tasks exceeding
+     * the limit will be removed from the end, shall be called on sorted tasks.
+     *
+     * @param limit number of tasks for the group to have. If greater
+     * than the task count, no action will be taken.
+     *
+     */
+    public applyTaskLimit(limit: number) {
+        this.tasks = this.tasks.slice(0, limit);
+    }
+
     /**
      * A markdown-format representation of all the tasks in this group.
      *

src/Query/TaskGroups.ts

@@ -133,4 +133,37 @@ export class TaskGroups {
             group.setGroupHeadings(displayHeadingSelector.getHeadingsForTaskGroup(group.groups));
         }
     }
+
+    /**
+     * Limits all {@link groups} to have a certain number of tasks and
+     * recalculates the {@link _totalTaskCount} for consistency.
+     *
+     * If no `group by ...` instructions were provided the limit is ignored,
+     * however there will be one task group.
+     *
+     * @param limit number of tasks for each group to have.
+     *
+     */
+    public applyTaskLimit(limit: number) {
+        if (this._groupers.length === 0) {
+            return;
+        }
+
+        this._groups.forEach((group) => {
+            group.applyTaskLimit(limit);
+        });
+
+        this.calculateTotalTaskCount();
+    }
+
+    private calculateTotalTaskCount() {
+        let concatenatedTasks: Task[] = [];
+
+        this._groups.forEach((group) => {
+            concatenatedTasks = [...concatenatedTasks, ...group.tasks];
+        });
+
+        const uniqueTasks = [...new Set(concatenatedTasks)];
+        this._totalTaskCount = uniqueTasks.length;
+    }
 }

tests/Query.test.ts

@@ -270,6 +270,8 @@ describe('Query parsing', () => {
             'hide urgency',
             'limit 42',
             'limit to 42 tasks',
+            'limit groups 31',
+            'limit groups to 31 tasks',
             'short mode',
             'short',
             'show backlink',
@@ -873,6 +875,17 @@ At most 1 task.
             const expectedDisplayText = `No filters supplied. All tasks will match the query.
 
 At most 0 tasks.
+`;
+            expect(query.explainQuery()).toEqual(expectedDisplayText);
+        });
+
+        it('should explain group limit 4', () => {
+            const input = 'limit groups 4';
+            const query = new Query({ source: input });
+
+            const expectedDisplayText = `No filters supplied. All tasks will match the query.
+
+At most 4 tasks per group.
 `;
             expect(query.explainQuery()).toEqual(expectedDisplayText);
         });
@@ -948,5 +961,49 @@ At most 0 tasks.
 `;
             expect('\n' + soleTaskGroup.tasksAsStringOfLines()).toStrictEqual(expectedTasks);
         });
+
+        it('should apply group limit correctly, after sorting tasks', () => {
+            // Arrange
+            const input = `
+                # sorting by description will sort the tasks alphabetically
+                sort by description
+
+                # grouping by status will give two groups: Done and Todo
+                group by status
+
+                # Apply a limit, to test which tasks make it to
+                limit groups 3
+                `;
+            const query = new Query({ source: input });
+
+            const tasksAsMarkdown = `
+- [x] Task 2 - will be in the first group and sorted after next one
+- [x] Task 1 - will be in the first group
+- [ ] Task 4 - will be sorted to 2nd place in the second group and pass the limit
+- [ ] Task 6 - will be sorted to 4th place in the second group and NOT pass the limit
+- [ ] Task 3 - will be sorted to 1st place in the second group and pass the limit
+- [ ] Task 5 - will be sorted to 3nd place in the second group and pass the limit
+            `;
+
+            const tasks = createTasksFromMarkdown(tasksAsMarkdown, 'some_markdown_file', 'Some Heading');
+
+            // Act
+            const groups = query.applyQueryToTasks(tasks);
+
+            // Assert
+            expect(groups.groups.length).toEqual(2);
+            expect(groups.totalTasksCount()).toEqual(5);
+            expect(groups.groups[0].tasksAsStringOfLines()).toMatchInlineSnapshot(`
+                "- [x] Task 1 - will be in the first group
+                - [x] Task 2 - will be in the first group and sorted after next one
+                "
+            `);
+            expect(groups.groups[1].tasksAsStringOfLines()).toMatchInlineSnapshot(`
+                "- [ ] Task 3 - will be sorted to 1st place in the second group and pass the limit
+                - [ ] Task 4 - will be sorted to 2nd place in the second group and pass the limit
+                - [ ] Task 5 - will be sorted to 3nd place in the second group and pass the limit
+                "
+            `);
+        });
     });
 });

tests/TaskGroups.test.ts

@@ -344,4 +344,123 @@ describe('Grouping tasks', () => {
             "
         `);
     });
+
+    it('should limit tasks in each group (no task overlapping across group)', () => {
+        // Arrange
+        const a = fromLine({ line: '- [ ] a', path: 'tasks_under_the_limit.md' });
+        const b = fromLine({ line: '- [ ] b', path: 'tasks_equal_to_limit.md' });
+        const c = fromLine({ line: '- [ ] c', path: 'tasks_equal_to_limit.md' });
+        const d = fromLine({ line: '- [ ] d', path: 'tasks_over_the_limit.md' });
+        const e = fromLine({ line: '- [ ] e', path: 'tasks_over_the_limit.md' });
+        const f = fromLine({ line: '- [ ] f', path: 'tasks_over_the_limit.md' });
+        const inputs = [a, b, c, d, e, f];
+
+        // Act
+        const grouping = [new PathField().createNormalGrouper()];
+        const groups = new TaskGroups(grouping, inputs);
+        groups.applyTaskLimit(2);
+
+        // Assert
+        expect(groups.totalTasksCount()).toEqual(5);
+        expect(groups.toString()).toMatchInlineSnapshot(`
+            "Groupers (if any):
+            - path
+
+            Group names: [tasks\\_equal\\_to\\_limit]
+            #### [path] tasks\\_equal\\_to\\_limit
+            - [ ] b
+            - [ ] c
+
+            ---
+
+            Group names: [tasks\\_over\\_the\\_limit]
+            #### [path] tasks\\_over\\_the\\_limit
+            - [ ] d
+            - [ ] e
+
+            ---
+
+            Group names: [tasks\\_under\\_the\\_limit]
+            #### [path] tasks\\_under\\_the\\_limit
+            - [ ] a
+
+            ---
+
+            5 tasks
+            "
+        `);
+    });
+
+    it('should limit tasks with tasks that overlap across multiple groups and correctly calculate unique tasks', () => {
+        // Arrange
+        const taskA = fromLine({ line: '- [ ] task A #tag1 #tag2' });
+        const taskB = fromLine({ line: '- [ ] task B #tag1 #tag3' });
+        const taskC = fromLine({ line: '- [ ] task C #tag3 #tag2' });
+        const taskD = fromLine({ line: '- [ ] task D #tag1 #tag2' });
+        const inputs = [taskA, taskB, taskC, taskD];
+
+        // Act
+        const grouping = [new TagsField().createNormalGrouper()];
+        const groups = new TaskGroups(grouping, inputs);
+        groups.applyTaskLimit(1);
+
+        // Assert
+        expect(groups.totalTasksCount()).toEqual(2);
+        expect(groups.toString()).toMatchInlineSnapshot(`
+            "Groupers (if any):
+            - tags
+
+            Group names: [#tag1]
+            #### [tags] #tag1
+            - [ ] task A #tag1 #tag2
+
+            ---
+
+            Group names: [#tag2]
+            #### [tags] #tag2
+            - [ ] task A #tag1 #tag2
+
+            ---
+
+            Group names: [#tag3]
+            #### [tags] #tag3
+            - [ ] task B #tag1 #tag3
+
+            ---
+
+            2 tasks
+            "
+        `);
+    });
+
+    it('should not limit tasks if no groups were specified', () => {
+        // Arrange
+        const taskA = fromLine({ line: '- [ ] task A' });
+        const taskB = fromLine({ line: '- [ ] task B' });
+        const taskC = fromLine({ line: '- [ ] task C' });
+        const taskD = fromLine({ line: '- [ ] task D' });
+        const inputs = [taskA, taskB, taskC, taskD];
+
+        // Act
+        const grouping: Grouper[] = [];
+        const groups = new TaskGroups(grouping, inputs);
+        groups.applyTaskLimit(1);
+
+        // Assert
+        expect(groups.totalTasksCount()).toEqual(4);
+        expect(groups.toString()).toMatchInlineSnapshot(`
+            "Groupers (if any):
+
+            Group names: []
+            - [ ] task A
+            - [ ] task B
+            - [ ] task C
+            - [ ] task D
+
+            ---
+
+            4 tasks
+            "
+        `);
+    });
 });