todo.next-occurrence

def next_occurrence(recurrence: Recurrence, due: str, today: str) -> str

from fune.todo.next_occurrence import next_occurrence  # todo.next-occurrence@^1

from .dates_add_days import add_days  ← from dates.add-days ^1.0.0 · built alongside by fune
from .dates_day_of_week import day_of_week  ← from dates.day-of-week ^1.0.0 · built alongside by fune
from .subscriptions_next_billing_date import next_billing_date  ← from subscriptions.next-billing-date ^1.0.0 · built alongside by fune
from .todo_item import Recurrence  ← from todo.item ^1.0.0 · built alongside by fune

_STEPS = {"daily": "day", "weekly": "week", "monthly": "month", "yearly": "year"}


def next_occurrence(recurrence: Recurrence, due: str, today: str) -> str:
    """The first date of the series strictly after both due and today.

    Every occurrence is the anchor plus whole intervals, so month ends stay
    month ends; finishing late skips the occurrences already missed.
    """
    frequency, interval, anchor = recurrence.frequency, recurrence.interval, recurrence.anchor
    if frequency != "weekdays" and frequency not in _STEPS:
        raise ValueError(f'unknown repeat frequency "{frequency}": expected daily, weekdays, weekly, monthly or yearly')
    if isinstance(interval, bool) or not isinstance(interval, int) or interval < 1:
        raise ValueError(f"repeat interval must be 1 or more, received {interval}")
    if frequency == "weekdays" and interval != 1:
        raise ValueError(f"weekday repeats cannot skip weeks: interval must be 1, received {interval}")
    add_days(anchor, 0)
    add_days(due, 0)
    add_days(today, 0)
    if anchor > due:
        raise ValueError(f"repeat anchor {anchor} is after the due date {due}")

    after = due if due > today else today
    if frequency == "weekdays":
        nxt = add_days(after, 1)
        while day_of_week(nxt) > 5:
            nxt = add_days(nxt, 1)
        return nxt
    return next_billing_date(anchor, _STEPS[frequency], interval, after)

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 4 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.next-occurrence

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

The whole function, every language, is one file too: todo.next-occurrence-1.0.0.fune, 15,072 bytes, sha256 7a616d4b47583508c619f5160c68a8331ae3c067991b69c5ff71283ffc3a8ff1. It installs into a project of any language.

# fune: before todo.next-occurrence

# fune: after todo.next-occurrence

# fune: replace dates.add-days in todo.next-occurrence
# fune: replace dates.day-of-week in todo.next-occurrence
# fune: replace subscriptions.next-billing-date in todo.next-occurrence
# fune: replace todo.item in todo.next-occurrence

# fune: step todo.next-occurrence after <n|label>

More from the author

Every occurrence is the recurrence's `anchor` (the first due date of the series) plus a whole number of intervals, computed with subscriptions.next-billing-date: `daily` steps in days, `weekly` in 7 days, `monthly` and `yearly` in calendar months with the month-end clamp. So a monthly todo anchored on 31 January is due 28 February, 31 March, 30 April; the classic bug is to add a month to the previous due date, which leaves it on the 28th for ever after February. A yearly todo anchored on 29 February is due 28 February in ordinary years and 29 February again in leap years. An interval of 2 on `weekly` is every other week, counted from the anchor's week.

`weekdays` is the next Monday to Friday. It has no interval other than 1 and its anchor does not matter.

## Which occurrence

The answer is the first date of the series strictly after both `due` and `today`:

- done on the day it is due: the next one (daily: tomorrow); - done early (a monthly bill due 1 October paid on 28 September): the one after the due date, 1 November, not 1 October again; - done late (a daily todo five days overdue): the next one after today, tomorrow. The missed occurrences are skipped rather than left overdue, which is what every to-do app does with a habit you catch up on.

`today` is an argument, never the clock: the app passes the user's local date.

## Errors

An unknown frequency, an interval below 1, a weekdays repeat with any other interval, an impossible date (dates.add-days's message) and an anchor after the due date are errors.

Files