todo.due-status

Where a todo stands against its due date today: done, overdue, today, tomorrow, this week, later or no date.

1.0.0 · published 2026-10-03 by charlie · Anterra

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

What it does

Where a todo stands against its due date today, as one of `done`, `overdue`, `today`, `tomorrow`, `this-week`, `later` or `none` (no due date). todo.due-label, todo.group-by-due and todo.summary are all built on it, so a todo is overdue in exactly one way everywhere in an app.

- `done` wins: a finished todo is never overdue, whatever its date. - `overdue` is a due date before today. Due dates have no time of day, so a todo due today is `today` until midnight, never overdue. - `this-week` is after tomorrow and no later than Sunday of the current ISO week (weeks start on Monday). On Saturday tomorrow is Sunday, and on Sunday tomorrow is already next week, so on those days nothing is `this-week`: Monday's todos are `later`. That is the calendar meaning of "this week", not "the next seven days".

For example

due_status(id t1, title Buy milk, notes —, done false, priority none, due 2026-09-27, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2026-09-28) → overdue due yesterday is overdue
due_status(id t1, title Buy milk, notes —, done false, priority none, due 2025-12-31, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2026-09-28) → overdue due last year is overdue
due_status(id t1, title Buy milk, notes —, done false, priority none, due 2026-09-28, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2026-09-28) → today due today is today, not overdue

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 due_status(todo: Todo, today: str) -> DueStatus

todo	Todo
today	date	the user's local date, from the app; never the clock
returns	DueStatus

The type it declares, generated into your project

DueStatus = Literal["done", "overdue", "today", "tomorrow", "this-week", "later", "none"]

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

from fune.todo.due_status import due_status  # todo.due-status@^1

impl/python.py · 27 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 .dates_day_of_week import day_of_week  ← from dates.day-of-week ^1.0.0 · built alongside by fune
from .dates_days_between import days_between  ← from dates.days-between ^1.0.0 · built alongside by fune
from .todo_due_status_types import DueStatus
from .todo_item import Todo  ← from todo.item ^1.0.0 · built alongside by fune


def due_status(todo: Todo, today: str) -> DueStatus:
    """One word for where a todo stands today; done wins, this-week is the rest of the ISO week."""
    # Check the dates first, so a bad date is an error even on a done todo.
    if todo.due is not None:
        days_between(today, todo.due)
    else:
        day_of_week(today)
    if todo.done:
        return "done"
    if todo.due is None:
        return "none"
    days = days_between(today, todo.due)
    if days < 0:
        return "overdue"
    if days == 0:
        return "today"
    if days == 1:
        return "tomorrow"
    if days <= 7 - day_of_week(today):
        return "this-week"
    return "later"

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.due-status

Download for Python todo.due-status-1.0.0-python.fune · 10,402 bytes sha256 f5cc1c05f18bc146b05e38af68d8866c42fe0168fecc5a0dd011e916068b6dc5

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

The whole function, every language, is one file too: todo.due-status-1.0.0.fune, 12,691 bytes, sha256 4922cabdc3416872cbc8b1ced81949f83081c366581e2bebbec8ba21fbacfacd. 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.due-status

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

# fune: after todo.due-status

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.due-status
# fune: replace dates.days-between in todo.due-status
# fune: replace todo.item in todo.due-status

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.due-status --steps.

# fune: step todo.due-status 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
due yesterday is overdue	id t1, title Buy milk, notes —, done false, priority none, due 2026-09-27, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2026-09-28	→	overdue
due last year is overdue	id t1, title Buy milk, notes —, done false, priority none, due 2025-12-31, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2026-09-28	→	overdue
due today is today, not overdue	id t1, title Buy milk, notes —, done false, priority none, due 2026-09-28, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2026-09-28	→	today
due tomorrow	id t1, title Buy milk, notes —, done false, priority none, due 2026-09-29, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2026-09-28	→	tomorrow
Wednesday, seen on Monday, is this week	id t1, title Buy milk, notes —, done false, priority none, due 2026-09-30, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2026-09-28	→	this-week
Sunday, seen on Monday, is still this week	id t1, title Buy milk, notes —, done false, priority none, due 2026-10-04, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2026-09-28	→	this-week
next Monday, seen on Monday, is later	id t1, title Buy milk, notes —, done false, priority none, due 2026-10-05, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2026-09-28	→	later
no due date	id t1, title Buy milk, notes —, done false, priority none, due —, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2026-09-28	→	none
a done todo is done even when its date has passed	id t1, title Buy milk, notes —, done true, priority none, due 2026-09-01, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at 2026-09-27T10:00:00Z, order 0, 2026-09…	→	done
a done todo with no date is done	id t1, title Buy milk, notes —, done true, priority none, due —, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at 2026-09-27T10:00:00Z, order 0, 2026-09-28	→	done

Show the other 9 tests

Case	Arguments		Expected
on Saturday, Sunday is tomorrow	id t1, title Buy milk, notes —, done false, priority none, due 2026-10-04, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2026-10-03	→	tomorrow
on Saturday, Monday is later: there is no rest of the week	id t1, title Buy milk, notes —, done false, priority none, due 2026-10-05, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2026-10-03	→	later
on Sunday, Monday is tomorrow and Tuesday is later	id t1, title Buy milk, notes —, done false, priority none, due 2026-10-06, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2026-10-04	→	later
on Thursday 31 December, Sunday 3 January is this week across the year end	id t1, title Buy milk, notes —, done false, priority none, due 2027-01-03, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2026-12-31	→	this-week
on Friday 26 February 2027, Sunday 28 February is this week	id t1, title Buy milk, notes —, done false, priority none, due 2027-02-28, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2027-02-26	→	this-week
today in the wrong format	id t1, title Buy milk, notes —, done false, priority none, due 2026-09-28, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 28/09/2026	→	error: is not an ISO date
a due date that never existed	id t1, title Buy milk, notes —, done false, priority none, due 2026-02-30, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2026-09-28	→	error: is not a real calendar date
a bad date is an error even on a done todo	id t1, title Buy milk, notes —, done true, priority none, due 2026-02-30, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at 2026-09-27T10:00:00Z, order 0, 2026-09…	→	error: is not a real calendar date
a bad today is an error even with no due date	id t1, title Buy milk, notes —, done false, priority none, due —, tags , recurrence —, created at 2026-09-20T09:00:00Z, completed at —, order 0, 2026-9-28	→	error: is not an ISO date

More from the author

`today` is the user's local date, passed in by the app; this capability never reads the clock. Malformed or impossible dates are errors (dates.add-days's messages), checked even on a done todo so that bad data is found early.

Files

Path	Bytes
README.md	1,060
impl/python.py	836
impl/rust.rs	1,148
impl/typescript.ts	1,008
vectors.json	5,929