@spec add_task(list_id(), task_id(), task_data()) :: :ok

Appends a new :todo task with the given ID and data to the end of the list. If the list does not exist or the task ID already exists, this call is ignored.

@spec all_tasks_complete?(list_id()) :: {:ok, boolean()}

Returns true if there are no remaining :todos in the list.

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec complete_task(list_id(), task_id(), task_result()) :: :ok

Marks the first task matching task_id as :done and stores the result. Only the first matching ID is updated; others are unchanged. No-op if list or task not found.

@spec fail_task(list_id(), task_id(), task_result()) :: :ok

Marks the first task matching task_id as :failed and stores the result. Only the first matching ID is updated; others are unchanged. No-op if list or task not found.

@spec get_description(list_id()) :: {:ok, binary() | nil} | {:error, :not_found}

Fetches the description of the specified task list. Returns {:ok, description} or {:error, :not_found}.

@spec get_list(list_id()) :: task_list() | {:error, :not_found}

Fetches all tasks for the given list in chronological (oldest-first) order. Returns {:error, :not_found} if the list does not exist.

@spec get_list_with_description(list_id()) ::
  {:ok, task_list(), binary() | nil} | {:error, :not_found}

Fetches tasks and description for the given list in a single call. Returns {:ok, tasks, description} or {:error, :not_found}.

@spec list_ids() :: [list_id()]

Returns all active task list IDs.

@spec new_task(task_id(), task_data(), keyword()) :: task()

Creates a new task with the given ID and data. Optionally accepts :outcome (default :todo) and :result (default nil).

@spec peek_task(list_id()) :: {:ok, task()} | {:error, :not_found} | {:error, :empty}

Returns {:ok, task} for the first :todo task in chronological order. Returns {:error, :empty} if no pending tasks, or {:error, :not_found} if the list does not exist.

@spec push_task(list_id(), task_id(), task_data()) :: :ok

Inserts a new :todo task with the given ID and data to the front of the list. If the list does not exist or the task ID already exists, this call is ignored.

@spec set_description(list_id(), binary()) :: :ok | {:error, :not_found}

Updates the description of the specified task list. Returns :ok or {:error, :not_found} if the list does not exist.

@spec start_list(
  %{optional(:id) => binary(), optional(:description) => binary()}
  | binary()
) ::
  list_id() | {:error, :exists}

Create a new task list with an optional slug id and description. If no id is provided, a unique slug of the form "tasks-<n>" is generated. If the id already exists, returns {:error, :exists}.