Changes to records

/**
 * Changes to a list of records, as values: what a grid, a list editor or a
 * collaborator did, in a form that can be told to the data's owner, applied,
 * and turned about to undo it.
 *
 * - `cells` — fields of records that stay where they are, each with the value
 *   it takes and the one it held.
 * - `insert` — records put in at a place.
 * - `remove` — records taken out, in runs, each at its place in the list as it
 *   was before any was taken.
 *
 * Applying a change shares every record it does not touch, so that whatever
 * else shows the data sees only what changed. The inverse of a change, applied
 * after it, gives back the list as it was: that is all undo needs.
 */
export type AnyRecord = Readonly<Record<string, unknown>>;

/** One field's change: where, what it holds now, and what it held. */
export interface CellChange {
  readonly row: number;
  /** The field's key in the record. */
  readonly key: string;
  readonly value: unknown;
  readonly previous: unknown;
}

/** Records side by side, and where the first of them is. */
export interface Run<R = AnyRecord> {
  readonly at: number;
  readonly rows: readonly R[];
}

export type RecordChange<R = AnyRecord> =
  | { readonly kind: "cells"; readonly cells: readonly CellChange[] }
  | ({ readonly kind: "insert" } & Run<R>)
  | { readonly kind: "remove"; readonly runs: ReadonlyArray<Run<R>> };

/** The list after a change. Records the change does not touch are the same objects. */
export function applyChange<R extends AnyRecord>(rows: readonly R[], change: RecordChange<R>): R[] {
  switch (change.kind) {
    case "cells": {
      const next = rows.slice();
      for (const { row, key, value } of change.cells) {
        // A change to a record that is not there has nothing to change.
        if (row >= 0 && row < next.length) next[row] = { ...next[row], [key]: value } as R;
      }
      return next;
    }
    case "insert":
      return rows.toSpliced(Math.min(Math.max(change.at, 0), rows.length), 0, ...change.rows);
    case "remove": {
      // One pass: a run is skipped as it is reached, however many there are.
      const next: R[] = [];
      let from = 0;
      for (const run of change.runs) {
        for (let index = from; index < run.at && index < rows.length; index += 1) next.push(rows[index]!);
        from = Math.max(from, run.at + run.rows.length);
      }
      for (let index = from; index < rows.length; index += 1) next.push(rows[index]!);
      return next;
    }
  }
}

/** The changes that undo a change, in the order to apply them. */
export function invertChange<R extends AnyRecord>(change: RecordChange<R>): Array<RecordChange<R>> {
  switch (change.kind) {
    case "cells":
      return [
        {
          kind: "cells",
          cells: change.cells.map((cell) => ({ ...cell, value: cell.previous, previous: cell.value })),
        },
      ];
    case "insert":
      return [{ kind: "remove", runs: [{ at: change.at, rows: change.rows }] }];
    case "remove":
      // Put back first to last: each run's place is its place once those before it are back.
      return change.runs.map((run) => ({ kind: "insert", at: run.at, rows: run.rows }));
  }
}

/**
 * The runs of records at the given places: the form a removal takes. The
 * places may come in any order, and more than once.
 */
export function runsOf<R extends AnyRecord>(rows: readonly R[], indexes: Iterable<number>): Array<Run<R>> {
  const sorted = [...new Set(indexes)]
    .filter((index) => Number.isInteger(index) && index >= 0 && index < rows.length)
    .toSorted((a, b) => a - b);
  const runs: Array<{ at: number; rows: R[] }> = [];
  for (const index of sorted) {
    const last = runs.at(-1);
    if (last !== undefined && last.at + last.rows.length === index) last.rows.push(rows[index]!);
    else runs.push({ at: index, rows: [rows[index]!] });
  }
  return runs;
}