todo.group-by-due

/** One section of a todo list grouped by due date. */
export interface DueGroup {
  readonly status: DueStatus;
  /** Overdue, Today, Tomorrow, This week, Later, No date or Done */
  readonly title: string;
  readonly todos: readonly Todo[];
}

export type SectionOrder = "due" | "input";

export function groupByDue(todos: readonly Todo[], today: string): readonly DueGroup[]

import { groupByDue } from "#fune/todo.group-by-due@^1";

import { type DueGroup } from "./todo_group_by_due_types.ts";
import { groupByDueWithOrder } from "./todo_group_by_due_group_by_due_with_order.ts";  ← groupByDueWithOrder, another function of this group · built into the same file, even by a slim install
import { type Todo } from "./todo_item.ts";  ← from todo.item ^1.0.0 · built alongside by fune

/**
 * Todos in planner sections, fixed order, empty sections left out. Sections
 * spanning several dates are sorted by due date, stably; the rest keep the
 * caller's order, so a list pre-sorted by priority stays that way.
 * groupByDueWithOrder(todos, today, "input") keeps the caller's order in
 * every section.
 */
export function groupByDue(todos: readonly Todo[], today: string): readonly DueGroup[] {
  return groupByDueWithOrder(todos, today, "due");
}

export function groupByDueWithOrder(todos: readonly Todo[], today: string, order: SectionOrder): readonly DueGroup[]

import { groupByDueWithOrder } from "#fune/todo.group-by-due@^1";

import { dayOfWeek } from "./dates_day_of_week.ts";  ← from dates.day-of-week ^1.0.0 · built alongside by fune
import { type DueStatus, dueStatus } from "./todo_due_status.ts";  ← from todo.due-status ^1.0.0 · built alongside by fune
import { type DueGroup, type SectionOrder } from "./todo_group_by_due_types.ts";
import { type Todo } from "./todo_item.ts";  ← from todo.item ^1.0.0 · built alongside by fune

const SECTIONS: readonly [DueStatus, string][] = [
  ["overdue", "Overdue"],
  ["today", "Today"],
  ["tomorrow", "Tomorrow"],
  ["this-week", "This week"],
  ["later", "Later"],
  ["none", "No date"],
  ["done", "Done"],
];

/**
 * Todos in planner sections, fixed order, empty sections left out. With
 * order "due", the sections spanning several dates (Overdue, This week,
 * Later) are sorted by due date, stably; with "input" every section keeps
 * the caller's order, so a list in manual order shows that order in each
 * section.
 */
export function groupByDueWithOrder(todos: readonly Todo[], today: string, order: SectionOrder): readonly DueGroup[] {
  if (order !== "due" && order !== "input") throw new Error(`order must be "due" or "input", found ${JSON.stringify(order)}`);
  dayOfWeek(today); // a bad today is an error even for an empty list
  const statuses = todos.map((todo) => dueStatus(todo, today));
  const groups: DueGroup[] = [];
  for (const [status, title] of SECTIONS) {
    const members = todos.filter((_, i) => statuses[i] === status);
    if (members.length === 0) continue;
    if (order === "due" && (status === "overdue" || status === "this-week" || status === "later")) {
      // Array.prototype.sort is stable, so equal dates keep input order.
      members.sort((a, b) => ((a.due as string) < (b.due as string) ? -1 : (a.due as string) > (b.due as string) ? 1 : 0));
    }
    groups.push({ status, title, todos: members });
  }
  return groups;
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the TypeScript 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

That builds the whole group. To build only what you call, and whatever it uses inside the group:

fune add todo.group-by-due --only groupByDue

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

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.

// fune: before todo.group-by-due.groupByDue
// fune: before todo.group-by-due.groupByDueWithOrder

// fune: after todo.group-by-due.groupByDue
// fune: after todo.group-by-due.groupByDueWithOrder

// 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

// fune: step todo.group-by-due.<fn> after <n|label>

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.

Files