Capstone 2: the task model

The second capstone is a command line task manager: a module example.com/tasks with a package tasks and a command cmd/tasks. It stores its tasks in a JSON file, has subcommands, a fake store for tests and a release with a version stamped in. The first lesson is the model, which is the only part that knows what a task is.

The Task struct

A task has an id, a title, a done flag and an optional due date. The due date is a *time.Time rather than a time.Time for one reason: omitempty does not omit a zero struct, so a value field writes 0001-01-01T00:00:00Z into every task. The pointer is nil when there is no due date, and the JSON key disappears.

package tasks import ( "errors" "fmt" "strings" "time" ) // ErrEmptyTitle is returned when a task has no title. var ErrEmptyTitle = errors.New("title is required") // Task is one item of the list. type Task struct { ID int `json:"id"` Title string `json:"title"` Done bool `json:"done"` Due *time.Time `json:"due,omitempty"` } // New returns a task with the title trimmed and the due date at midnight UTC. func New(id int, title string, due time.Time) (Task, error) { title = strings.TrimSpace(title) if title == "" { return Task{}, ErrEmptyTitle } if title == "TODO" { return Task{}, fmt.Errorf("title %q is a placeholder, write the real one", title) } if due.IsZero() { return Task{ID: id, Title: title}, nil } day := due.UTC().Truncate(24 * time.Hour) return Task{ID: id, Title: title, Due: &day}, nil } // Toggle flips the done flag and returns the new value. func (t *Task) Toggle() bool { t.Done = !t.Done return t.Done } // String renders a task as one line for a person. func (t Task) String() string { mark := " " if t.Done { mark = "x" } line := fmt.Sprintf("[%s] %d %s", mark, t.ID, t.Title) if t.Due != nil { line += " (due " + t.Due.Format("2006-01-02") + ")" } return line }

The struct is the shape of the file and of the JSON output of lesson 126, which is why the tags are here and not in a separate DTO. A small program can afford one type for the domain and the wire; a service with a public API often separates them, and the notes service of the next capstone does.

New and validation

New is the only way to build a task, and it owns the two rules: the title is trimmed and must not be empty, and the due date is moved to midnight UTC. A title of TODO is rejected as a placeholder, which is a rule of this program and not of task lists in general; the point is that a rule lives in one function and every caller gets it.

The error for an empty title is a sentinel, ErrEmptyTitle, so a caller can wrap it, compare it with errors.Is and map it to a status. The placeholder error is built with fmt.Errorf and has no sentinel, because no caller needs to act on it differently: it is an input mistake with a message.

Toggle and String

Toggle flips the flag on a pointer receiver and returns the new value, and String writes the one-line form the list command prints: a checkbox, the id, the title and the due date when there is one. The method set is the difference between a value and a pointer here: a Task value has String, a *Task has both, and the list loop prints values.

The model in a program

The demo builds a task with a due date, prints it, toggles it and makes the two mistakes on purpose so the messages and the exit codes are the real ones.

package main import ( "fmt" "time" "example.com/tasks/tasks" ) func main() { due := time.Date(2026, 11, 20, 15, 30, 0, 0, time.UTC) task, err := tasks.New(1, " buy milk ", due) fmt.Println("error:", err) fmt.Println("title:", task.Title) fmt.Println("due:", task.Due.Format("2006-01-02")) fmt.Println("line:", task) fmt.Println("toggled:", task.Toggle()) fmt.Println("line:", task) _, err = tasks.New(2, " ", time.Time{}) fmt.Println("empty:", err) fmt.Println("exit code:", tasks.ExitCode(err)) _, err = tasks.New(3, "TODO", time.Time{}) fmt.Println("placeholder:", err) fmt.Println("exit code:", tasks.ExitCode(err)) }

go run ./cmd/l121

error: <nil>
title: buy milk
due: 2026-11-20
line: [ ] 1 buy milk (due 2026-11-20)
toggled: true
line: [x] 1 buy milk (due 2026-11-20)
empty: title is required
exit code: 4
placeholder: title "TODO" is a placeholder, write the real one
exit code: 1

The title came back trimmed, the due time was dropped to the day, and the two failures have different statuses: 4 for the empty title, which the caller can map to a specific message, and 1 for the generic placeholder. The exit codes are the subject of lesson 124.

A model with rules

A model that validates is a model a command can trust. New is the gate, the fields are exported for the JSON encoder but the invariants are set by the constructor, and a program that loads a file gets the same treatment by decoding into the struct and checking the rules it cares about. The alternative, a struct with no rules and validation scattered in the handlers, is how two commands disagree about what a valid task is.

The next lesson gives the model a home on disk.

Exercises

  1. Add a rule that a title longer than eighty characters is an error with its own sentinel. Which function changes, and how does the command map the new error?
  2. Change the due date to a value field and marshal a task without one. What appears in the JSON, and why does the pointer avoid it?
  3. Make Toggle a value receiver and run the demo. What happens to the task, and what does the compiler say?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. Why is Due a *time.Time?

    Answer

    omitempty does not omit a zero struct, the pointer does

    A nil pointer drops the key.

  2. What does New do with the title?

    Answer

    Trims it and rejects an empty one

    The rule lives in the constructor.

  3. What is ErrEmptyTitle?

    Answer

    A sentinel the caller can test with errors.Is

    It is mapped to status 4.

  4. What does Toggle return?

    Answer

    The new done value

    The command prints the task after it.

  5. Which receiver does Toggle need?

    Answer

    A pointer, because it changes the task

    A value receiver would flip a copy.

  6. What does String print for a done task?

    Answer

    [x] 1 buy milk

    The checkbox is the first field.

  7. Where is the due time moved?

    Answer

    To midnight UTC of the day

    A due date is a day.

  8. Why is a placeholder title rejected?

    Answer

    It is a rule of this program, enforced in one place

    It has no sentinel because nobody acts on it differently.

  9. What does the list command print a task with?

    Answer

    The String method

    The one-line form is the model method.

  10. What is the model responsible for?

    Answer

    The rules that make a task valid

    Storage and commands come next.

The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev