task-status.enum.ts

/**
 * The lifecycle states a task can occupy.
 *
 * String values are used so they serialise cleanly over JSON / WebSocket
 * and read well in logs and the frontend.
 */
export enum TaskStatus {
  Todo = 'todo',
  InProgress = 'in_progress',
  Done = 'done',
  Archived = 'archived',
}

/**
 * The status transition state machine.
 *
 * Each key maps to the set of statuses it is legal to move *to*. Keeping the
 * rules in a single declarative table makes the policy trivial to audit and
 * extend — adding a new state or edge is a one-line change here, with no
 * branching logic scattered across services.
 *
 *   todo        → in_progress | archived
 *   in_progress → todo | done | archived
 *   done        → archived            (cannot reopen to todo)
 *   archived    → (terminal)
 */
export const TASK_STATUS_TRANSITIONS: Readonly<
  Record<TaskStatus, readonly TaskStatus[]>
> = {
  [TaskStatus.Todo]: [TaskStatus.InProgress, TaskStatus.Archived],
  [TaskStatus.InProgress]: [
    TaskStatus.Todo,
    TaskStatus.Done,
    TaskStatus.Archived,
  ],
  [TaskStatus.Done]: [TaskStatus.Archived],
  [TaskStatus.Archived]: [],
};

/**
 * Returns true when moving `from` → `to` is permitted by the state machine.
 * A no-op transition (from === to) is treated as illegal so callers get a
 * descriptive error rather than silently re-writing `updatedAt`.
 */
export function canTransition(from: TaskStatus, to: TaskStatus): boolean {
  return TASK_STATUS_TRANSITIONS[from].includes(to);
}