app/lib/blog-listing.mjs

Functions

Imports

It imports no other module of this repo. Imported by app/components/taxonomy-listing.tsx, app/db/posts.ts, app/routes/admin.media._index.tsx, app/routes/blog._index.tsx, app/routes/blog.series.$series.tsx, app/routes/blog.tags.$tag.tsx.

Source

1export const POSTS_PER_PAGE = 10;
2
3/** The home page's Writing section is a taste, not a feed: the featured post and two more. */
4export const HOME_CARDS = 3;
5
6/**
7 * The essays that follow the featured post on the home page, in this order. `featured` marks one post
8 * (it leads /writing), so the rest of the home page's best-of is a hand-picked list. A pick that is
9 * not published drops out and the newest post fills its place; test/blog-listing.test.mjs holds each
10 * pick against a published file in content/posts.
11 */
12export const HOME_PICKS = ["policy-in-the-api-not-the-mcp", "observable-plot-inside-a-worker"];
13
14/**
15 * The home page's picks first, in `picks` order, then everything else in the order given. Stable, so
16 * the rest stay newest first. Duplicates by slug are dropped, because the caller merges two queries.
17 *
18 * @template {{ slug: string }} T
19 * @param {T[]} rows none of them featured
20 * @param {readonly string[]} [picks]
21 * @returns {T[]}
22 */
23export function picksFirst(rows, picks = HOME_PICKS) {
24  const seen = new Set();
25  const unique = rows.filter((row) => !seen.has(row.slug) && seen.add(row.slug));
26  const rank = (/** @type {string} */ slug) => {
27    const i = picks.indexOf(slug);
28    return i === -1 ? picks.length : i;
29  };
30  return unique
31    .map((row, i) => ({ row, i }))
32    .sort((a, b) => rank(a.row.slug) - rank(b.row.slug) || a.i - b.i)
33    .map(({ row }) => row);
34}
35
36/**
37 * A `?page=` a listing can use: a positive whole number, else 1. `-3`, `1.5` and `abc` all read as 1.
38 *
39 * @param {string | null} raw
40 */
41export function readPage(raw) {
42  if (raw === null || !/^\d+$/.test(raw)) return 1;
43  const page = Number(raw);
44  return page > 0 && Number.isSafeInteger(page) ? page : 1;
45}
46
47/**
48 * @param {number} position 1-based
49 * @param {number} [perPage]
50 */
51export function pageForPosition(position, perPage = POSTS_PER_PAGE) {
52  return Math.floor((position - 1) / perPage) + 1;
53}
54
55/**
56 * An empty corpus still has one page, because /writing renders an empty state rather than a 404.
57 *
58 * @param {number} total
59 * @param {number} [perPage]
60 */
61export function pageCount(total, perPage = POSTS_PER_PAGE) {
62  return Math.max(1, Math.ceil(total / perPage));
63}
64
65/**
66 * Returns the list with the hero REMOVED, or it renders twice. Matched by slug, not identity,
67 * because a serialization boundary upstream would silently break identity.
68 *
69 * @template {{ slug: string, featured?: boolean }} T
70 * @param {T[]} posts the page of posts, in order
71 * @param {boolean} eligible whether this request may show a hero at all
72 * @returns {{ featured: T | null, posts: T[] }}
73 */
74export function splitFeatured(posts, eligible) {
75  if (!eligible) return { featured: null, posts };
76  const featured = posts.find((post) => post.featured) ?? null;
77  if (!featured) return { featured: null, posts };
78  return { featured, posts: posts.filter((post) => post.slug !== featured.slug) };
79}
80
81/**
82 * A pure function rather than SQL because the offline machine-readable check renders this section
83 * without a database. With no featured post the newest leads. `others` must exclude the featured
84 * post or it prints twice.
85 *
86 * @template {{ slug: string }} T
87 * @param {T[]} featuredRows at most one, the featured post
88 * @param {T[]} others in the order they follow the lead, none of them featured: `picksFirst` for the home page
89 * @param {number} [cards] how many the section shows in total, lead included
90 * @returns {{ featured: T | null, recent: T[] }}
91 */
92export function startHere(featuredRows, others, cards = HOME_CARDS) {
93  const lead = featuredRows[0] ?? others[0] ?? null;
94  if (lead === null) return { featured: null, recent: [] };
95  const recent = featuredRows[0] ? others.slice(0, cards - 1) : others.slice(1, cards);
96  return { featured: lead, recent };
97}
98
99
100/**
101 * The facts describe the FILTERED list, not the corpus: a tag view stating the whole blog's span
102 * would be true of something the page does not show. A null is not a zero; the row omits itself.
103 *
104 * @param {number} total posts in the whole filtered list, not on this page of it
105 * @param {{ firstYear: string | null, lastYear: string | null, minutes: number | null }} span
106 * @returns {(string | null)[]} three facts, in the row's order
107 */
108export function listingFacts(total, span) {
109  const years =
110    span.firstYear && span.lastYear
111      ? span.firstYear === span.lastYear
112        ? span.firstYear
113        : `${span.firstYear} to ${span.lastYear}`
114      : null;
115  // Hours only past two: "1 hour" rounded from 38 minutes would be wrong.
116  const reading = span.minutes
117    ? span.minutes >= 120
118      ? `${Math.round(span.minutes / 60)} hours of reading`
119      : `${span.minutes} minutes of reading`
120    : null;
121  return [`${total} post${total === 1 ? "" : "s"}`, years, reading];
122}