Template method.

export type Item = { id: string; title: string };
export type Rows = readonly (readonly string[])[];
export type Outcome =
  | 'imported'
  | 'invalid-row'
  | 'empty-batch'
  | 'invalid-id'
  | 'empty-title'
  | 'duplicate-id'
  | 'write-failed';
export type Stage = 'decode' | 'normalize' | 'validate' | 'commit';
// row is one-based; 0 means the whole batch.
export type ImportReport = {
  outcome: Outcome;
  row: number;
  trace: Stage[];
  candidate: Item[];
  saved: Item[];
};
export type Decoded = { items: Item[]; row: number };

const copy = (items: readonly Item[]): Item[] =>
  items.map((item) => ({ ...item }));

// The whole catalog is replaced at once, or not at all.
export class Catalog {
  private items: Item[];
  private fail: boolean;

  constructor(initial: readonly Item[], fail = false) {
    this.items = copy(initial);
    this.fail = fail;
  }

  // false: the store refused the write, before changing anything.
  replace(items: readonly Item[]): boolean {
    if (this.fail) return false;
    this.items = copy(items);
    return true;
  }

  snapshot(): Item[] {
    return copy(this.items);
  }
}

// Every row must have exactly two cells; the first bad row stops decoding.
export function decodeColumns(rows: Rows, titleFirst: boolean): Decoded {
  const items: Item[] = [];
  for (let i = 0; i < rows.length; i++) {
    const row = rows[i];
    if (row.length !== 2) return { items: [], row: i + 1 };
    const [id, title] = titleFirst ? [row[1], row[0]] : [row[0], row[1]];
    items.push({ id, title });
  }
  return { items, row: 0 };
}

// Trims ASCII spaces and tabs only; other whitespace is data.
export function trimFields(items: readonly Item[]): Item[] {
  const trim = (s: string) => s.replace(/^[ \t]+|[ \t]+$/g, '');
  return items.map(({ id, title }) => ({ id: trim(id), title: trim(title) }));
}

const validId = /^[a-z][a-z0-9-]{0,23}$/;

// The shared batch rule, on the values the catalog would receive.
type Check = { outcome: Outcome | 'valid'; row: number };

export function validate(items: readonly Item[]): Check {
  if (!items.length) return { outcome: 'empty-batch', row: 0 };
  const seen = new Set<string>();
  for (let i = 0; i < items.length; i++) {
    const { id, title } = items[i];
    if (!validId.test(id)) return { outcome: 'invalid-id', row: i + 1 };
    if (title === '') return { outcome: 'empty-title', row: i + 1 };
    if (seen.has(id)) return { outcome: 'duplicate-id', row: i + 1 };
    seen.add(id);
  }
  return { outcome: 'valid', row: 0 };
}

export abstract class ImportTemplate {
  protected abstract decode(rows: Rows): Decoded;

  protected normalize(items: readonly Item[]): Item[] {
    return copy(items);
  }

  // The template method. TypeScript has no `final`: a subclass can still
  // replace run, so keep the subclasses few and reviewed.
  run(rows: Rows, catalog: Catalog): ImportReport {
    const trace: Stage[] = ['decode'];
    const done = (outcome: Outcome, row: number, candidate: Item[]) => ({
      outcome,
      row,
      trace: [...trace],
      candidate: copy(candidate),
      saved: catalog.snapshot(),
    });
    const decoded = this.decode(rows);
    if (decoded.row) return done('invalid-row', decoded.row, []);
    trace.push('normalize');
    const candidate = this.normalize(decoded.items);
    trace.push('validate');
    const check = validate(candidate);
    if (check.outcome !== 'valid') {
      return done(check.outcome, check.row, candidate);
    }
    trace.push('commit');
    const saved = catalog.replace(candidate);
    return done(saved ? 'imported' : 'write-failed', 0, candidate);
  }
}

// `override` (TypeScript 4.3) makes the compiler check that the base still
// has the method; noImplicitOverride makes the keyword required.
export class IdTitleImporter extends ImportTemplate {
  protected override decode(rows: Rows): Decoded {
    return decodeColumns(rows, false);
  }
}

export class TitleIdImporter extends ImportTemplate {
  protected override decode(rows: Rows): Decoded {
    return decodeColumns(rows, true);
  }
}

export class TrimmedImporter extends IdTitleImporter {
  protected override normalize(items: readonly Item[]): Item[] {
    return trimFields(items);
  }
}

export class TrimmedTitleIdImporter extends TitleIdImporter {
  protected override normalize(items: readonly Item[]): Item[] {
    return trimFields(items);
  }
}

export type Layout = 'id-title' | 'title-id';

// Two layouts and an optional trim make four subclasses.
export function createImporter(layout: Layout, trim: boolean): ImportTemplate {
  if (layout === 'id-title') {
    return trim ? new TrimmedImporter() : new IdTitleImporter();
  }
  if (layout === 'title-id') {
    return trim ? new TrimmedTitleIdImporter() : new TitleIdImporter();
  }
  throw new Error(`unknown layout: ${String(layout)}`);
}