todo.group-by-due

Split todos into Overdue, Today, Tomorrow, This week, Later, No date and Done sections, in that order.

1.0.0 (not the latest) · published 2026-10-03 by charlie · Anterra

Pinned by 14 tests, run in TypeScript, Python and Rust.

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.

Sections always come in this order, and only those with at least one todo are returned:

For example

group_by_due(, 2026-09-28) → an empty list has no sections
group_by_due(todos ×7, 2026-09-28) → ×7 one todo of each kind, in reverse, comes out in section order
group_by_due(todos ×3, 2026-09-28) → ×1 overdue is sorted by due date, oldest first

The function

The same function in TypeScript, Python and Rust, pinned by the same tests. Pick your language; the choice follows you around the registry.

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

The type 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]

Your code names it in one line, in the file that uses it

from fune.todo.group_by_due import group_by_due  # todo.group-by-due@^1

impl/python.py · 34 lines · open · raw

Imports 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 .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
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(todos: Sequence[Todo], today: str) -> List[DueGroup]:
    """Todos in planner sections, fixed order, empty sections left out."""
    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 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 groups

Install

fune build

With 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-due

Download for Python todo.group-by-due-1.0.0-python.fune · 23,906 bytes sha256 b54a601dcba853a24f95f725781c1b43cc74c175379871790c1c14063770edd9

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./todo.group-by-due-1.0.0-python.fune, or fetch it from a terminal with fune pull todo.group-by-due@1.0.0:python.

The whole function, every language, is one file too: todo.group-by-due-1.0.0.fune, 27,566 bytes, sha256 1481e318e0c34459c62eda3eb94aeb9446f0f310526596be41943d6b38f8f888. 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

after — your function gets the result and the arguments, and returns the final result.

# fune: after todo.group-by-due

replace — 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-due

step — your function runs at a numbered point inside the 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 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.

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

More from the author

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

Files

Path	Bytes
README.md	1,223
impl/python.py	1,203
impl/rust.rs	2,009
impl/typescript.ts	1,447
vectors.json	16,743