todo.sort

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { foldAscii } from "./collections_search_text.ts";  ← from collections.search-text ^1.0.0 · built alongside by fune
import { sortBy } from "./collections_sort_by.ts";  ← from collections.sort-by ^1.0.0 · built alongside by fune
import { type SortDirection } from "./collections_sort_by_types.ts";
import { type Todo } from "./todo_item.ts";  ← from todo.item ^1.0.0 · built alongside by fune
import { isUtcTimestamp } from "./todo_item_validate_todo.ts";
import { type TodoSortKey } from "./todo_sort_types.ts";

const RANKS: Record<string, number> = { none: 0, low: 1, medium: 2, high: 3 };

/** Sort passes, least significant first; the last pass is the primary key and takes the direction. */
const PASSES: Record<string, [string, "asc" | "desc" | "dir"][]> = {
  manual: [["created", "asc"], ["order", "dir"]],
  due: [["order", "asc"], ["rank", "desc"], ["due", "dir"]],
  priority: [["order", "asc"], ["due", "asc"], ["rank", "dir"]],
  created: [["order", "asc"], ["created", "dir"]],
  title: [["order", "asc"], ["title", "dir"]],
};

function rank(priority: string): number {
  const r = RANKS[priority];
  if (r === undefined || !Object.prototype.hasOwnProperty.call(RANKS, priority)) {
    throw new RangeError(`unknown priority "${priority}": expected none, low, medium or high`);
  }
  return r;
}

/**
 * A creation time that sorts as text: the fraction padded to nine digits, so
 * "...:00Z" (no fraction) comes before "...:00.5Z" as it should, where the raw
 * strings would put "." before "Z".
 */
function createdKey(createdAt: string): string {
  if (!isUtcTimestamp(createdAt)) {
    throw new RangeError(`createdAt "${createdAt}" is not a UTC timestamp, e.g. 2026-09-28T09:30:00Z`);
  }
  const fraction = createdAt.length > 20 ? createdAt.slice(20, createdAt.length - 1) : "";
  return createdAt.slice(0, 19) + "." + fraction.padEnd(9, "0");
}

/**
 * Todos in the order a list shows them for the chosen key. Stable, built from
 * collections.sort-by passes from the least to the most significant key. The
 * direction flips only the primary key; tie-breakers always run ascending, and
 * todos with no due date stay last in both directions.
 */
export function sortTodos(todos: readonly Todo[], by: TodoSortKey, direction: SortDirection): readonly Todo[] {
  const passes = Object.prototype.hasOwnProperty.call(PASSES, by) ? PASSES[by] : undefined;
  if (passes === undefined) {
    throw new RangeError(`unknown sort key "${by}": expected manual, due, priority, created or title`);
  }
  if (direction !== "asc" && direction !== "desc") {
    throw new RangeError(`direction must be "asc" or "desc", received "${direction}"`);
  }
  const used = new Set(passes.map(([field]) => field));
  let records: readonly Readonly<Record<string, unknown>>[] = todos.map((todo, i) => {
    const r: Record<string, unknown> = { i, order: todo.order };
    if (used.has("created")) r.created = createdKey(todo.createdAt);
    if (used.has("rank")) r.rank = rank(todo.priority);
    if (used.has("due")) r.due = todo.due ?? null;
    if (used.has("title")) r.title = foldAscii(todo.title);
    return r;
  });
  for (const [field, dir] of passes) {
    records = sortBy(records, field, dir === "dir" ? direction : dir);
  }
  return records.map((r) => todos[r.i as number]);
}