todo.item

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

import { daysInMonth } from "./dates_add_days.ts";  ← from dates.add-days ^1.0.0 · built alongside by fune
import { type TodoDraft, type TodoValidation } from "./todo_item_types.ts";

export const MAX_TITLE = 200;
export const MAX_NOTES = 2000;
export const MAX_TAGS = 10;
export const MAX_TAG_LENGTH = 30;
export const MAX_INTERVAL = 999;

const PRIORITIES = ["none", "low", "medium", "high"];
const FREQUENCIES = ["daily", "weekdays", "weekly", "monthly", "yearly"];

/**
 * Trim ASCII whitespace only. String.prototype.trim, Python's strip and Rust's
 * trim each know a different set of Unicode spaces, so "trimmed" would mean
 * three different things; a title stored by one service must read the same
 * in the others.
 */
export function trimSpace(text: string): string {
  const isSpace = (c: string) => c === " " || c === "\t" || c === "\n" || c === "\r" || c === "\v" || c === "\f";
  let start = 0;
  let end = text.length;
  while (start < end && isSpace(text[start])) start++;
  while (end > start && isSpace(text[end - 1])) end--;
  return text.slice(start, end);
}

/** Length in Unicode code points, the count every language agrees on. */
export function codePointLength(text: string): number {
  let n = 0;
  for (const _ of text) n++;
  return n;
}

function digits(text: string, from: number, to: number): boolean {
  for (let i = from; i < to; i++) {
    const c = text.charCodeAt(i);
    if (c < 48 || c > 57) return false;
  }
  return true;
}

/** A real calendar date written YYYY-MM-DD, years 0001 to 9999. Never throws. */
export function isIsoDate(text: unknown): boolean {
  if (typeof text !== "string" || text.length !== 10 || text[4] !== "-" || text[7] !== "-") return false;
  if (!digits(text, 0, 4) || !digits(text, 5, 7) || !digits(text, 8, 10)) return false;
  const year = Number(text.slice(0, 4));
  const month = Number(text.slice(5, 7));
  const day = Number(text.slice(8, 10));
  return year >= 1 && month >= 1 && month <= 12 && day >= 1 && day <= daysInMonth(year, month);
}

/** A tag in normal form: lower-case ASCII letters and digits in runs joined by single hyphens. */
function isTagForm(tag: string): boolean {
  if (tag.length === 0 || tag[0] === "-" || tag[tag.length - 1] === "-") return false;
  for (let i = 0; i < tag.length; i++) {
    const c = tag[i];
    const ok = (c >= "a" && c <= "z") || (c >= "0" && c <= "9") || (c === "-" && tag[i - 1] !== "-");
    if (!ok) return false;
  }
  return true;
}

function titleError(title: string): string | null {
  const trimmed = trimSpace(title);
  if (trimmed.length === 0) return "Enter a title.";
  for (const ch of trimmed) {
    const code = ch.codePointAt(0) as number;
    if (code < 0x20 || code === 0x7f) return "Keep the title to one line, without control characters.";
  }
  if (codePointLength(trimmed) > MAX_TITLE) return `Use no more than ${MAX_TITLE} characters for the title.`;
  return null;
}

function tagsError(tags: readonly string[]): string | null {
  if (tags.length > MAX_TAGS) return `Use no more than ${MAX_TAGS} tags.`;
  const seen: string[] = [];
  for (const tag of tags) {
    if (!isTagForm(tag)) return `Tag "${tag}" can only use lower-case letters, digits and single hyphens.`;
    if (tag.length > MAX_TAG_LENGTH) return `Tag "${tag}" is longer than ${MAX_TAG_LENGTH} characters.`;
    if (seen.includes(tag)) return `Tag "${tag}" is listed twice.`;
    seen.push(tag);
  }
  return null;
}

function recurrenceError(draft: TodoDraft): string | null {
  const rule = draft.recurrence;
  if (rule === null || rule === undefined) return null;
  if (!FREQUENCIES.includes(rule.frequency)) return "Choose how it repeats: daily, weekdays, weekly, monthly or yearly.";
  if (!Number.isInteger(rule.interval) || rule.interval < 1 || rule.interval > MAX_INTERVAL) {
    return `Repeat every 1 to ${MAX_INTERVAL} days, weeks, months or years.`;
  }
  if (rule.frequency === "weekdays" && rule.interval !== 1) return "Weekday repeats cannot skip weeks; use an interval of 1.";
  if (!isIsoDate(rule.anchor)) return "Enter the repeat start as a real date, YYYY-MM-DD.";
  if (draft.due === null || draft.due === undefined) return "A repeating todo needs a due date.";
  if (isIsoDate(draft.due) && rule.anchor > draft.due) return "The repeat cannot start after the due date.";
  return null;
}

/**
 * The edit rules as ordered [field, message] pairs, for validateTodo to merge
 * its own checks into field order.
 */
export function draftErrors(draft: TodoDraft): [string, string][] {
  const errors: [string, string][] = [];
  const title = titleError(draft.title);
  if (title !== null) errors.push(["title", title]);
  if (draft.notes !== null && draft.notes !== undefined && codePointLength(draft.notes) > MAX_NOTES) {
    errors.push(["notes", `Use no more than ${MAX_NOTES} characters for the notes.`]);
  }
  if (!PRIORITIES.includes(draft.priority)) errors.push(["priority", "Choose a priority: none, low, medium or high."]);
  if (draft.due !== null && draft.due !== undefined && !isIsoDate(draft.due)) {
    errors.push(["due", "Enter the due date as a real date, YYYY-MM-DD."]);
  }
  const tags = tagsError(draft.tags);
  if (tags !== null) errors.push(["tags", tags]);
  const recurrence = recurrenceError(draft);
  if (recurrence !== null) errors.push(["recurrence", recurrence]);
  return errors;
}

/**
 * Check what a person typed into the add or edit form. The title is judged
 * trimmed, because the list operations trim it before storing; everything
 * else is judged as given.
 */
export function validateDraft(draft: TodoDraft): TodoValidation {
  const errors = Object.fromEntries(draftErrors(draft));
  return { valid: Object.keys(errors).length === 0, errors };
}

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

import { draftErrors, isIsoDate, trimSpace } from "./todo_item_validate_draft.ts";  ← validateDraft, another function of this group · built into the same file, even by a slim install
import { type Todo, type TodoValidation } from "./todo_item_types.ts";

const FIELD_ORDER = ["id", "title", "notes", "priority", "due", "tags", "recurrence", "createdAt", "completedAt", "order"];

/**
 * An ISO 8601 UTC timestamp as JavaScript's toISOString and most databases
 * write it: YYYY-MM-DDTHH:MM:SS, optional fraction of 1 to 9 digits, then Z.
 * Offsets other than Z are refused so that two timestamps compare as strings.
 */
export function isUtcTimestamp(text: unknown): boolean {
  if (typeof text !== "string" || text.length < 20) return false;
  if (!isIsoDate(text.slice(0, 10)) || text[10] !== "T" || text[13] !== ":" || text[16] !== ":") return false;
  const two = (at: number, max: number) => {
    const a = text.charCodeAt(at) - 48;
    const b = text.charCodeAt(at + 1) - 48;
    return a >= 0 && a <= 9 && b >= 0 && b <= 9 && a * 10 + b <= max;
  };
  if (!two(11, 23) || !two(14, 59) || !two(17, 59)) return false;
  let rest = text.slice(19);
  if (rest[0] === ".") {
    let n = 1;
    while (n < rest.length && rest.charCodeAt(n) >= 48 && rest.charCodeAt(n) <= 57) n++;
    if (n === 1 || n > 10) return false;
    rest = rest.slice(n);
  }
  return rest === "Z";
}

/**
 * Check a stored todo: the draft rules, plus what only a stored item has
 * (an id, a trimmed title, timestamps, a completion time exactly when done,
 * an order). Use it on anything read back from storage or imported.
 */
export function validateTodo(todo: Todo): TodoValidation {
  const found = new Map<string, string>(draftErrors(todo));
  if (trimSpace(todo.id).length === 0) found.set("id", "Every todo needs an id.");
  if (!found.has("title") && trimSpace(todo.title) !== todo.title) found.set("title", "Remove the spaces around the title.");
  if (!isUtcTimestamp(todo.createdAt)) found.set("createdAt", "Record when it was created as a UTC timestamp, e.g. 2026-09-28T09:30:00Z.");
  const completedAt = todo.completedAt ?? null;
  if (todo.done && completedAt === null) found.set("completedAt", "A done todo needs the time it was completed.");
  else if (!todo.done && completedAt !== null) found.set("completedAt", "An open todo cannot have a completion time.");
  else if (completedAt !== null && !isUtcTimestamp(completedAt)) {
    found.set("completedAt", "Record when it was completed as a UTC timestamp, e.g. 2026-09-28T09:30:00Z.");
  }
  if (!Number.isInteger(todo.order) || todo.order < 0) found.set("order", "Order must be a whole number, 0 or more.");
  const errors: Record<string, string> = {};
  for (const field of FIELD_ORDER) {
    const message = found.get(field);
    if (message !== undefined) errors[field] = message;
  }
  return { valid: Object.keys(errors).length === 0, errors };
}