app/lib/carrel/roster-handler.server.ts

Functions

Imports

It imports app/db/roster.ts, app/lib/carrel/content-kinds.server.ts, app/lib/carrel/errors.server.ts, app/lib/editor/github.server.ts, app/lib/roster/compile.mjs, app/lib/roster/save.server.ts. Imported by app/lib/carrel/site-adapter.server.ts.

Source

1// The roster kind of Carrel's /content group (docs/ROSTER.md): ids are `roster.<year>` (the registry encodes
2// them), the year being the cohort's file key (content/roster/2025.md). Every write is saveRoster, the one
3// path a cohort reaches the repository by, so a cohort saved through Carrel is validated by the code CI
4// runs, committed, written to D1 and live on the next request with no deploy. There is no editor in the
5// site's admin for this kind and no operator save tool. A cohort has no draft state: it is public when it
6// is saved, so saving and publishing are the same write and unpublishing is refused.
7
8import { RefusedError, VersionConflictError } from "@dustinedwards/site-api";
9import type { ContentSummary, WriteResult } from "@dustinedwards/site-api";
10
11import { listRosterRows } from "~/db/roster";
12import type { ContentKindHandler } from "~/lib/carrel/content-kinds.server";
13import { asSiteApiError } from "~/lib/carrel/errors.server";
14import { fileRevisions, fileRevisionSource, readFile } from "~/lib/editor/github.server";
15import { ROSTER_PAGE_PATH, rosterPath } from "~/lib/roster/compile.mjs";
16import { COHORT_SLUG, saveRoster } from "~/lib/roster/save.server";
17
18type RosterEnv = Env & { GITHUB_TOKEN?: string };
19
20/** A revision's version is a commit sha; an item's own version is the blob sha of its file. */
21
22/** The title Carrel shows: the cohort's year, which is all a cohort is named. */
23const titleOf = (slug: string) => `${slug} cohort`;
24
25export function rosterHandler(env: RosterEnv): ContentKindHandler {
26  /** One write through saveRoster as the Carrel actor, answered in the package's terms. */
27  async function write(slug: string, changeId: string, raw: string, expectedVersion: string | null): Promise<WriteResult> {
28    try {
29      const saved = await saveRoster(env, {
30        slug,
31        raw,
32        expectedBlobSha: expectedVersion ?? undefined,
33        isNew: expectedVersion === null,
34        actor: { kind: "carrel", changeId },
35      });
36      return { id: slug, version: saved.sourceBlobSha, status: "published", changeId };
37    } catch (error) {
38      // A RosterInvalid carries every message the validator gave; asSiteApiError passes them on.
39      return asSiteApiError(env, error, rosterPath(slug));
40    }
41  }
42
43  /** A slug that is not a year owns no file, so a read of it is a missing id and never a path to read. */
44  const owns = (slug: string) => COHORT_SLUG.test(slug);
45
46  return {
47    kind: "roster",
48
49    async list(query) {
50      const needle = query.q?.toLowerCase();
51      const summaries: ContentSummary[] = (await listRosterRows(env)).map((row) => ({
52        id: row.slug,
53        kind: "roster",
54        title: titleOf(row.slug),
55        status: "published",
56        // A cohort has no page of its own: it is listed on the program page, under its heading.
57        path: `${ROSTER_PAGE_PATH}#year-${row.year}`,
58        publishAt: null,
59        publishedAt: null,
60        updatedAt: row.syncedAt.toISOString(),
61      }));
62      return summaries
63        .filter((s) => !query.status || s.status === query.status)
64        .filter((s) => !needle || s.title.toLowerCase().includes(needle) || s.id.includes(needle));
65    },
66
67    async get(slug) {
68      if (!owns(slug)) return null;
69      const file = await readFile(env, rosterPath(slug));
70      if (!file) return null;
71      const row = await env.DB.prepare(`SELECT synced_at FROM roster WHERE slug = ?1`).bind(slug).first<{ synced_at: number }>();
72      return {
73        id: slug,
74        kind: "roster",
75        title: titleOf(slug),
76        status: "published",
77        path: `${ROSTER_PAGE_PATH}#year-${slug}`,
78        publishAt: null,
79        publishedAt: null,
80        updatedAt: row ? new Date(row.synced_at * 1000).toISOString() : null,
81        format: "markdown",
82        source: file.content,
83        version: file.sha,
84      };
85    },
86
87    // Creates a cohort (no version) or edits one (its version), as every kind does; either way it is public.
88    async saveDraft(slug, input) {
89      if (!owns(slug)) throw new RefusedError(`"${slug}" is not a cohort file key; a cohort is named for its year, such as 2025.`);
90      const file = await readFile(env, rosterPath(slug));
91      if (input.expectedVersion === null && file) throw new VersionConflictError(file.sha);
92      if (input.expectedVersion !== null && !file) throw new VersionConflictError(null);
93      return write(slug, input.changeId, input.source, input.expectedVersion);
94    },
95
96    async publish(slug, input) {
97      if (!owns(slug)) throw new RefusedError(`"${slug}" is not a cohort file key; a cohort is named for its year, such as 2025.`);
98      // Read even when source is sent: a version for an id that does not exist is a conflict.
99      const file = await readFile(env, rosterPath(slug));
100      if (!file) throw new VersionConflictError(null);
101      return write(slug, input.changeId, input.source ?? file.content, input.expectedVersion);
102    },
103
104    async unpublish() {
105      throw new RefusedError(
106        "A roster cohort has no draft state, so it cannot be unpublished. To remove a cohort, delete its file " +
107          "from content/roster/ in a commit; the next content sync removes its row.",
108      );
109    },
110
111    revisions(slug) {
112      return fileRevisions(env, owns(slug) ? rosterPath(slug) : null);
113    },
114
115    revisionSource(slug, version) {
116      return fileRevisionSource(env, owns(slug) ? rosterPath(slug) : null, version);
117    },
118  };
119}