todo.group-by-due
Split todos into Overdue, Today, Tomorrow, This week, Later, No date and Done sections, in that order.
1.1.0 · published 2026-10-03 by charlie · Anterra
Pinned by 26 tests, run in TypeScript, Python and Rust.groupByDue 14 · groupByDueWithOrder 12
What it does
Splits a todo list into the sections a planner shows, using todo.due-status for every todo so the sections agree with the labels and the summary.
| Function | Order inside a section | | --- | --- | | `groupByDue(todos, today)` | Overdue, This week and Later by due date; the rest as given (below). Unchanged since 1.0.0. | | `groupByDueWithOrder(todos, today, order)` | `order` `"due"`: the same as `groupByDue`. `"input"`: every section keeps the order the todos came in. |
The functions
A group: 2 functions that work together, each in its own file, each pinned by its own tests in TypeScript, Python and Rust. A project can install only the ones it calls.
- group_by_due (todos: Todo[], today: date) -> DueGroup[]
- group_by_due_with_order (todos: Todo[], today: date, order: SectionOrder) -> DueGroup[]
The types it declares, generated into your project
@dataclass(frozen=True)
class DueGroup:
"""One section of a todo list grouped by due date."""
status: DueStatus
#: Overdue, Today, Tomorrow, This week, Later, No date or Done
title: str
todos: List[Todo]
SectionOrder = Literal["due", "input"]Once installed, your code imports each one from the group's module.
group_by_due throws on bad input 14 tests
def group_by_due(todos: Sequence[Todo], today: str) -> List[DueGroup]| todos | Todo[] | in the order the caller wants within a section, e.g. already sorted by priority |
| today | date | the user's local date, from the app; never the clock |
| returns | DueGroup[] | only the sections that have todos, in the fixed order; Overdue, This week and Later sorted by date |
For example
group_by_due(, 2026-09-28)→ an empty list has no sectionsgroup_by_due(todos ×7, 2026-09-28)→ ×7 one todo of each kind, in reverse, comes out in section ordergroup_by_due(todos ×3, 2026-09-28)→ ×1 overdue is sorted by due date, oldest first
from fune.todo.group_by_due import group_by_due # todo.group-by-due@^1Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.
from typing import List, Sequence
from .todo_group_by_due_group_by_due_with_order import group_by_due_with_order ← groupByDueWithOrder, another function of this group · built into the same file, even by a slim install
from .todo_group_by_due_types import DueGroup
from .todo_item import Todo ← from todo.item ^1.0.0 · built alongside by fune
def group_by_due(todos: Sequence[Todo], today: str) -> List[DueGroup]:
"""Todos in planner sections, fixed order, empty sections left out; multi-date sections sorted by date."""
return group_by_due_with_order(todos, today, "due")group_by_due_with_order throws on bad input 12 tests
def group_by_due_with_order(todos: Sequence[Todo], today: str, order: SectionOrder) -> List[DueGroup]| todos | Todo[] | in the order the caller wants |
| today | date | the user's local date, from the app; never the clock |
| order | SectionOrder | due sorts Overdue, This week and Later by date (groupByDue); input keeps the caller's order in every section |
| returns | DueGroup[] | only the sections that have todos, in the fixed order |
For example
group_by_due_with_order(todos ×2, 2026-09-28, input)→ ×1 input keeps overdue in the caller's order, not by dategroup_by_due_with_order(todos ×2, 2026-09-28, due)→ ×1 due sorts the same overdue todos oldest first, as groupByDue doesgroup_by_due_with_order(todos ×2, 2026-09-28, input)→ ×1 input keeps this week in the caller's order
from fune.todo.group_by_due import group_by_due_with_order # todo.group-by-due@^1Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.
import json
from typing import List, Sequence
from .dates_day_of_week import day_of_week ← from dates.day-of-week ^1.0.0 · built alongside by fune
from .todo_due_status import due_status ← from todo.due-status ^1.0.0 · built alongside by fune
from .todo_group_by_due_types import DueGroup, SectionOrder
from .todo_item import Todo ← from todo.item ^1.0.0 · built alongside by fune
SECTIONS = [
("overdue", "Overdue"),
("today", "Today"),
("tomorrow", "Tomorrow"),
("this-week", "This week"),
("later", "Later"),
("none", "No date"),
("done", "Done"),
]
SORTED_BY_DUE = ("overdue", "this-week", "later")
def group_by_due_with_order(todos: Sequence[Todo], today: str, order: SectionOrder) -> List[DueGroup]:
"""Todos in planner sections; order "due" sorts the multi-date sections by date, "input" keeps input order."""
if order not in ("due", "input"):
raise ValueError(f'order must be "due" or "input", found {json.dumps(order)}')
day_of_week(today) # a bad today is an error even for an empty list
statuses = [due_status(todo, today) for todo in todos]
groups: List[DueGroup] = []
for status, title in SECTIONS:
members = [todo for todo, s in zip(todos, statuses) if s == status]
if not members:
continue
if order == "due" and status in SORTED_BY_DUE:
# sorted is stable, so equal dates keep input order.
members = sorted(members, key=lambda todo: todo.due or "")
groups.append(DueGroup(status=status, title=title, todos=members)) # type: ignore[arg-type]
return groupsInstall
fune buildWith that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:
fune add todo.group-by-dueThat builds the whole group. To build only what you call, and whatever it uses inside the group:
fune add todo.group-by-due --only groupByDueThe manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./todo.group-by-due-1.1.0-python.fune, or fetch it from a terminal with fune pull todo.group-by-due@1.1.0:python.
The whole function, every language, is one file too: todo.group-by-due-1.1.0.fune, 49,637 bytes, sha256 d36f8e49fb579f388a1115d49410ca12ebca4b45e0d52da7f61191aa63236dd6. It installs into a project of any language.
Customise it in your app
The seams this capability offers. Put a marker directly above a function of your own and fune build wires it into the built code; the package on the registry is not changed, the built file’s header lists it under CUSTOMISED, and fune hooks lists every hook in the project. How hooks work.
before — your function gets the arguments and returns them, changed or not, or throws to refuse the call.
# fune: before todo.group-by-due.groupByDue
# fune: before todo.group-by-due.groupByDueWithOrderafter — your function gets the result and the arguments, and returns the final result.
# fune: after todo.group-by-due.groupByDue
# fune: after todo.group-by-due.groupByDueWithOrderreplace — inside this capability’s code only, calls to a dependency go to your function, with the same signature. Other capabilities that use it are unaffected; write in * to replace it everywhere.
# fune: replace dates.day-of-week in todo.group-by-due
# fune: replace todo.due-status in todo.group-by-due
# fune: replace todo.item in todo.group-by-duestep — your function runs at a numbered point inside a function’s body, receives the in-scope values it names as parameters, and may return replacements. List the points with fune show todo.group-by-due --steps.
# fune: step todo.group-by-due.<fn> after <n|label>Tests
A version published now needs at least 8 tests for every function, and one that expects the error for each function that throws; the registry refuses it otherwise. fune verify --all runs each case in TypeScript, Python and Rust, and a project runs them again with fune verify. This page lists the cases; it does not run them. The exact JSON is vectors.json.
groupByDue 14 tests
| Case | Arguments | Expected | |
|---|---|---|---|
| an empty list has no sections | , 2026-09-28 | → | |
| one todo of each kind, in reverse, comes out in section order | todos ×7, 2026-09-28 | → | ×7 |
| overdue is sorted by due date, oldest first | todos ×3, 2026-09-28 | → | ×1 |
| equal due dates keep their input order (stable) | todos ×4, 2026-09-28 | → | ×1 |
| equal overdue dates keep their input order | todos ×2, 2026-09-28 | → | ×1 |
| this week is sorted by due date | todos ×3, 2026-09-28 | → | ×1 |
| today keeps the caller's order | todos ×3, 2026-09-28 | → | ×1 |
| done keeps the caller's order, whatever the dates | todos ×3, 2026-09-28 | → | ×1 |
| no date keeps the caller's order, and empty sections are left out | todos ×3, 2026-09-28 | → | ×2 |
| on Saturday there is no This week: Sunday is tomorrow, Monday is later | todos ×3, 2026-10-03 | → | ×2 |
Show the other 4 tests
| Case | Arguments | Expected | |
|---|---|---|---|
| a list that is all done is one Done section | todos ×2, 2026-09-28 | → | ×1 |
| a malformed today is an error even for an empty list | , 2026-9-28 | → | error: is not an ISO date |
| today with a trailing newline | todos ×1, 2026-09-28 | → | error: is not an ISO date |
| a due date that never existed | todos ×2, 2026-09-28 | → | error: is not a real calendar date |
groupByDueWithOrder 12 tests
| Case | Arguments | Expected | |
|---|---|---|---|
| input keeps overdue in the caller's order, not by date | todos ×2, 2026-09-28, input | → | ×1 |
| due sorts the same overdue todos oldest first, as groupByDue does | todos ×2, 2026-09-28, due | → | ×1 |
| input keeps this week in the caller's order | todos ×2, 2026-09-28, input | → | ×1 |
| input keeps later in the caller's order | todos ×3, 2026-09-28, input | → | ×1 |
| due sorts later by date | todos ×3, 2026-09-28, due | → | ×1 |
| input still puts the sections in their fixed order | todos ×6, 2026-09-28, input | → | ×6 |
| an empty list has no sections | , 2026-09-28, input | → | |
| a list sorted by priority stays in priority order inside overdue | todos ×2, 2026-09-28, input | → | ×1 |
| due keeps equal dates in input order (stable) | todos ×3, 2026-09-28, due | → | ×1 |
| manual order across several sections: each keeps its members' input order | todos ×4, 2026-09-28, input | → | ×2 |
Show the other 2 tests
| Case | Arguments | Expected | |
|---|---|---|---|
| a malformed today is an error even for an empty list | , 28/09/2026, input | → | error: is not an ISO date |
| an unknown order is an error | , 2026-09-28, manual | → | error: order must be "due" or "input" |
More from the author
Sections always come in this order, and only those with at least one todo are returned:
| status | title | | --- | --- | | overdue | Overdue | | today | Today | | tomorrow | Tomorrow | | this-week | This week | | later | Later | | none | No date | | done | Done |
- **Overdue, This week and Later are sorted by due date**, earliest first, because they span several dates. The sort is stable: todos with the same due date keep their input order. - **Today, Tomorrow, No date and Done keep the input order**, since every todo in them has the same date (or none). So sort first by whatever you prefer (priority, manual order, title) and the grouping keeps it inside each section and among equal dates. - The titles are English. A localised app maps `status` to its own strings. - "This week" is the rest of the ISO week after tomorrow (see todo.due-status): on Saturday and Sunday there is no This week section. - `today` is checked even for an empty list, and a malformed or impossible date anywhere is an error (dates.add-days's messages).
## New in 1.1.0: keeping the caller's order
`groupByDue` re-sorts the sections that span several dates, which is right for a planner sorted by date but wrong for a list in the person's own (manual, drag-and-drop) order: dragging a todo above another in Later would snap back. `groupByDueWithOrder(todos, today, "input")` keeps the order the todos came in, in every section, so sort first (todo.sort's manual order, priority, title...) and the sections show that order. Which section a todo goes in is the same either way.
`groupByDue` is now `groupByDueWithOrder(todos, today, "due")` and answers exactly as 1.0.0 did: every 1.0.0 vector is kept. An `order` other than `"due"` or `"input"` is an error (`order must be "due" or "input", found "manual"`), checked before `today`.
1.0.0 was one function in one file; 1.1.0 is a group of two (see `spec/AUTHORING.md`, Groups), so `import { groupByDue } from "#fune/todo.group-by-due@^1"` keeps working.