todo.import-csv

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

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

/**
 * Todos from CSV text as todo.export-csv writes it, or as a spreadsheet saves
 * it: the 13 columns in any order, CRLF or LF, an optional byte order mark.
 * Every row is checked with validateTodo; the first problem is thrown with
 * its row number, counting the header as row 1. validateTodoCsv lists them
 * all.
 */
export function importCsv(csv: string): readonly Todo[] {
  const reading = readTodoCsv(csv);
  if (reading.problems.length > 0) throw new Error(reading.problems[0].thrown);
  return reading.todos;
}

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

import { type CsvRowError, type CsvValidation } from "./todo_import_csv_types.ts";
import { type Recurrence, type Todo, validateTodo } from "./todo_item.ts";  ← from todo.item ^1.0.0 · built alongside by fune
import { normaliseTags } from "./todo_normalise_tags.ts";  ← from todo.normalise-tags ^1.0.0 · built alongside by fune

const COLUMNS = [
  "id", "title", "notes", "done", "priority", "due", "tags",
  "recurrenceFrequency", "recurrenceInterval", "recurrenceAnchor", "createdAt", "completedAt", "order",
];
const HEADER_RULE = "the header must have the columns " + COLUMNS.join(", ");
const WHOLE = /^-?[0-9]{1,15}$/;

/** One problem, and the message importCsv throws when it is the first. */
export interface TodoCsvProblem {
  error: CsvRowError;
  thrown: string;
}

/** What reading a whole file found: the good rows' todos, and every problem. */
export interface TodoCsvReading {
  todos: Todo[];
  rows: number;
  problems: TodoCsvProblem[];
}

/**
 * One RFC 4180 record starting at `start`: its fields and where the next
 * record starts (after its CRLF or LF), or the reason it cannot be read.
 * Inside quotes everything, CR and LF included, is kept as it is.
 */
function recordAt(text: string, start: number): { fields: string[]; next: number } | string {
  const fields: string[] = [];
  let pos = start;
  for (;;) {
    let value = "";
    if (text[pos] === '"') {
      pos++;
      for (;;) {
        const quote = text.indexOf('"', pos);
        if (quote < 0) return "a quoted field is not closed";
        value += text.slice(pos, quote);
        if (text[quote + 1] === '"') {
          value += '"';
          pos = quote + 2;
        } else {
          pos = quote + 1;
          break;
        }
      }
      if (pos < text.length && text[pos] !== "," && text[pos] !== "\r" && text[pos] !== "\n") {
        return "text after the closing quote of a field";
      }
    } else {
      let end = pos;
      while (end < text.length && text[end] !== "," && text[end] !== "\r" && text[end] !== "\n") {
        if (text[end] === '"') return "a field with a double quote in it must be quoted";
        end++;
      }
      value = text.slice(pos, end);
      pos = end;
    }
    fields.push(value);
    if (pos >= text.length) return { fields, next: pos };
    if (text[pos] === ",") {
      pos++;
    } else if (text[pos] === "\n") {
      return { fields, next: pos + 1 };
    } else if (text[pos + 1] === "\n") {
      return { fields, next: pos + 2 };
    } else {
      return "a CR outside quotes must be followed by LF";
    }
  }
}

/** Where each of COLUMNS sits in the file's header, or what is wrong with it. */
function columnsAt(names: string[]): number[] | string {
  const at = new Map<string, number>();
  for (let i = 0; i < names.length; i++) {
    const name = names[i];
    if (!COLUMNS.includes(name)) return `${HEADER_RULE}: unknown column "${name}"`;
    if (at.has(name)) return `${HEADER_RULE}: column "${name}" appears twice`;
    at.set(name, i);
  }
  const out: number[] = [];
  for (const name of COLUMNS) {
    const i = at.get(name);
    if (i === undefined) return `${HEADER_RULE}: missing column "${name}"`;
    out.push(i);
  }
  return out;
}

function wholeNumber(text: string): number | null {
  if (!WHOLE.test(text)) return null;
  const n = Number(text);
  return n === 0 ? 0 : n; // "-0" is 0, not JavaScript's -0
}

/**
 * Reads the whole file, collecting every problem rather than stopping at the
 * first. Checks run in the order importCsv 1.0.0 ran them, so the first
 * problem is the one it threw. A header or a record that cannot be split
 * into fields ends the reading, since the rows after it cannot be found.
 */
export function readTodoCsv(csv: string): TodoCsvReading {
  const text = csv.startsWith("") ? csv.slice(1) : csv;
  const todos: Todo[] = [];
  const problems: TodoCsvProblem[] = [];
  const ids = new Set<string>();
  let at: number[] | null = null;
  let row = 0;
  let rows = 0;
  let pos = 0;
  const add = (field: string | null, message: string, thrown: string) =>
    problems.push({ error: { row, field, message }, thrown });
  while (pos < text.length) {
    if (text[pos] === "\n") {
      pos++;
      continue;
    }
    if (text[pos] === "\r" && text[pos + 1] === "\n") {
      pos += 2;
      continue;
    }
    row++;
    const record = recordAt(text, pos);
    if (typeof record === "string") {
      add(null, record, `row ${row}: ${record}`);
      break;
    }
    pos = record.next;
    const fields = record.fields;
    if (at === null) {
      const header = columnsAt(fields);
      if (typeof header === "string") {
        add(null, header, header);
        break;
      }
      at = header;
      continue;
    }
    rows++;
    if (fields.length !== COLUMNS.length) {
      const message = `expected ${COLUMNS.length} fields, found ${fields.length}`;
      add(null, message, `row ${row}: ${message}`);
      continue;
    }
    const before = problems.length;
    const plain = (field: string, message: string) => add(field, message, `row ${row}: ${message}`);
    const [id, title, notes, done, priority, due, tags, frequency, interval, anchor, createdAt, completedAt, order] =
      (at as number[]).map((i) => fields[i]);

    const doneRead = done === "true" || done === "false";
    if (!doneRead) plain("done", `done must be true or false, found "${done}"`);
    const filled = [frequency, interval, anchor].filter((t) => t !== "").length;
    let recurrence: Recurrence | null = null;
    let recurrenceRead = true;
    if (filled === 3) {
      const every = wholeNumber(interval);
      if (every === null) {
        plain("recurrenceInterval", `recurrenceInterval must be a whole number, found "${interval}"`);
        recurrenceRead = false;
      } else {
        recurrence = { frequency: frequency as Recurrence["frequency"], interval: every, anchor };
      }
    } else if (filled !== 0) {
      plain("recurrence", "fill in all three recurrence columns or leave them all empty");
      recurrenceRead = false;
    }
    const position = wholeNumber(order);
    if (position === null) plain("order", `order must be a whole number, found "${order}"`);

    const todo: Todo = {
      id,
      title,
      notes: notes === "" ? null : notes,
      done: done === "true",
      priority: priority as Todo["priority"],
      due: due === "" ? null : due,
      tags: normaliseTags(tags.split(" ")),
      recurrence,
      createdAt,
      completedAt: completedAt === "" ? null : completedAt,
      order: position ?? 0,
    };
    // A column that could not be read has already been reported; the
    // stand-in value must not raise a second, misleading message.
    const errors = validateTodo(todo).errors;
    for (const field of Object.keys(errors)) {
      if (field === "completedAt" && !doneRead) continue;
      if (field === "recurrence" && !recurrenceRead) continue;
      if (field === "order" && position === null) continue;
      add(field, errors[field], `row ${row}: ${field}: ${errors[field]}`);
    }
    if (!("id" in errors)) {
      if (ids.has(id)) plain("id", `duplicate id "${id}"`);
      ids.add(id);
    }
    if (problems.length === before) todos.push(todo);
  }
  if (at === null && problems.length === 0) {
    row = 1;
    add(null, "the CSV has no header row", "the CSV has no header row");
  }
  return { todos, rows, problems };
}

/**
 * Every problem in a todo CSV file, row by row, for a screen that lists them
 * all: the row (header = 1), the field or column, and the message. The
 * file is valid exactly when importCsv would accept it.
 */
export function validateTodoCsv(csv: string): CsvValidation {
  const reading = readTodoCsv(csv);
  return { valid: reading.problems.length === 0, rows: reading.rows, errors: reading.problems.map((p) => p.error) };
}