Choosing the shape of a session

Every function in readlog takes a session, a list of sessions, or produces one. So the shape of a session is not a detail you can fix later — it is the thing seven functions have to agree about. Choose it badly and each of them pays: one has to trim the title, another has to guess whether pages is text or a number, a third has to cope with tags arriving sometimes as a string and sometimes as a list.

Choose it well and most of those functions become two or three boring lines. That is the actual measure of a good data shape: the functions that use it are dull. If your functions are full of 'but what if this field is…' then the shape is wrong, and no amount of clever code will rescue it.

So this lesson comes before any of the real behaviour. You are deciding what a session IS, in exactly five fields, and where the cleaning up happens.

A record is a group of values that belong to the same real thing. A reading session is one sitting with one book: which book, how many pages, how many minutes, what kind of book it was, and whether you finished it. Five fields, one sitting. Everything else — totals, averages, tallies by tag — is worked out from a list of these, never stored inside one of them.

That last rule matters more than it looks. If you put a runningTotal field inside a session, you have two copies of the truth, and the day they disagree you will not know which one to believe. A record holds facts about itself. Anything computed from many records is computed on demand, by a function.

So the canonical session is: title (text), pages (number), minutes (number), tags (a list of text), finished (true or false). That is the whole shape, and every function in the rest of the module can rely on it.

Think of passport control at an airport. Everything messy — different documents, different queues, different languages — is dealt with at one gate. Past that gate, everyone inside the building has been checked in the same way, so nothing further in has to ask again.

Your library needs the same gate. The raw entry comes from a form, so the title may have stray spaces, the numbers may be text ('42' rather than 42) and the tags may be one comma-separated string. One function, toSession, turns that into the canonical shape. Every other function is written as if the world were tidy, because past that gate it is.

The alternative — each function defending itself against every possible mess — is the shape of code that never feels finished. The same trim() ends up in six places, one of them missing a case, and the bug is impossible to locate because there is no single place where the truth is decided.

There is a real cost to this choice, and it is worth naming: converting silently is not the same as validating. toSession will happily turn nonsense into a number and hand it on. Lesson 4 builds the validator that stands beside it. Cleaning and checking are two jobs, and mixing them into one function makes both harder to test.

A field called time holding 90 is a small landmine. Ninety what — minutes, seconds, pages, a clock time? Every reader has to go and find out, and one of them will guess wrong. A field called minutes holding 90 needs no explanation and cannot be misread.

This is the cheapest quality improvement in programming. Not durationInMinutes, which is long enough to be annoying, just minutes. Same for pages rather than count, and title rather than name (a name could be the author's).

The rule generalises: if a reader would have to ask a question to use your field, put the answer in the field's name. You are not writing for the compiler, which does not care, but for the next person to open the file.

It is tempting to arrange a record into little boxes: book: { title: 'Dune' }, effort: { pages: 30, minutes: 45 }. It looks organised. It is not, at this size — every reader now writes session.book.title, every function has one more level to get wrong, and the nesting expresses no fact about reading sessions.

Nest when the nested thing is genuinely a thing on its own, with several fields and its own identity that would survive being pulled out. A book has an author, a year and a title, so a bigger version of readlog might well have a book record with sessions pointing at it. Version 1 does not need that, and building it now would be paying for a feature the brief did not ask for.

Flat records also serialise cleanly: JSON.stringify of a flat record is readable, and comparing two of them in a test is straightforward. Both of those matter in the lessons ahead.

Tags arrive as one string, so you split them: 'fiction, classic'.split(',') gives you the pieces, still carrying their spaces, and map with trim() cleans each one. So far so good — and then someone submits the form with the tags box empty.

''.split(',') is not an empty list. It is a list of ONE item: the empty string. MDN states the rule plainly — when the string is empty and the separator is not, split returns an array containing one empty string. So your tidy list of tags now contains a tag that is nothing at all, session.tags.length says 1, and 'how many tags does this have' answers wrongly for every untagged entry in the log.

The fix is one filter: keep only the pieces whose length is greater than zero. That same filter also cleans up 'fiction,,prize' and a trailing comma, which is exactly the kind of thing a real form produces. Add it once, in toSession, and no other function ever meets the problem.

The shape comes first, because every function has to agree about it. A record holds facts about one thing; anything computed from many records is a function, not a field. Cleaning happens once, at the door, so the rest of the library can assume a tidy world — but cleaning is not checking, and lesson 4 adds the other half. Put units in field names. Stay flat until nesting expresses a real thing. And remember that splitting an empty string gives you a list of one empty piece, so filter the blanks out.