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

Functions

Imports

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

Source

1// The "page" kind of Carrel's content group (docs/PAGES.md): the Research, Teaching and Software prose
2// pages. The id is `page.<slug>`, the slug being the file key (`research-phages` for /research/phages).
3// Every write is savePage, the one page save, so a page saved through Carrel is validated by the code
4// CI runs, committed, written to D1 and live on the next request with no deploy. A page cannot be
5// created here: its address is structure and lives in CONTENT_PAGE_PATHS, so an id no registered path
6// names is refused, and a save that names a missing file is a conflict like a post's.
7
8import { RefusedError, VersionConflictError } from "@dustinedwards/site-api";
9import type { ContentStatus, ContentSummary, WriteResult } from "@dustinedwards/site-api";
10import matter from "gray-matter";
11
12import { listPageRows } from "~/db/pages";
13import type { ContentKindHandler } from "~/lib/carrel/content-kinds.server";
14import { asSiteApiError } from "~/lib/carrel/errors.server";
15import { withPublication } from "~/lib/carrel/front-matter-lines";
16import { fileRevisions, fileRevisionSource, readFile } from "~/lib/editor/github.server";
17import { PAGES_DIR, pagePathForSlug, pageSourcePath } from "~/lib/pages/compile.mjs";
18import { savePage } from "~/lib/pages/save.server";
19
20type PageEnv = Env & { GITHUB_TOKEN?: string };
21
22/** A revision's version is a commit sha; an item's own version is the blob sha of its file. */
23
24const isDraft = (raw: string) => matter(raw).data.draft === true;
25const statusOf = (raw: string): ContentStatus => (isDraft(raw) ? "draft" : "published");
26
27export function pageHandler(env: PageEnv): ContentKindHandler {
28  /** The path and file of a registered slug, or null: an id no registered path names owns nothing. */
29  function registered(slug: string) {
30    const path = pagePathForSlug(slug);
31    return path ? { path, file: pageSourcePath(slug) } : null;
32  }
33
34  /** The same, for a write: a missing registration is a refusal that says why. */
35  function target(slug: string) {
36    const found = registered(slug);
37    if (!found) {
38      throw new RefusedError(
39        `"${slug}" names no registered page. A save cannot create a page: its address is added to ` +
40          `CONTENT_PAGE_PATHS (app/lib/content-pages.mjs) in code first. The files are in ${PAGES_DIR}/.`,
41      );
42    }
43    return found;
44  }
45
46  /** One write through savePage as the Carrel actor, answered in the package's terms. */
47  async function write(slug: string, changeId: string, raw: string, expectedVersion: string | null): Promise<WriteResult> {
48    const { path } = target(slug);
49    try {
50      const saved = await savePage(env, {
51        path,
52        raw,
53        expectedBlobSha: expectedVersion ?? undefined,
54        isNew: false,
55        actor: { kind: "carrel", changeId },
56      });
57      return { id: slug, version: saved.sourceBlobSha, status: saved.draft ? "draft" : "published", changeId };
58    } catch (error) {
59      // A PageInvalid carries every message the validator gave; asSiteApiError passes them on.
60      return asSiteApiError(env, error, target(slug).file);
61    }
62  }
63
64  /** The stored file for a write that names a version; a version for a missing file is a conflict. */
65  async function existing(slug: string): Promise<string> {
66    const file = await readFile(env, target(slug).file);
67    if (!file) throw new VersionConflictError(null);
68    return file.content;
69  }
70
71  /** The source with its draft flag set to `draft`, touching no line when it already says so. */
72  const withDraft = (raw: string, draft: boolean) =>
73    isDraft(raw) === draft ? raw : withPublication(raw, { draft });
74
75  return {
76    kind: "page",
77
78    async list(query) {
79      const needle = query.q?.toLowerCase();
80      const summaries: ContentSummary[] = (await listPageRows(env)).map((row) => {
81        const status: ContentStatus = row.draft ? "draft" : "published";
82        return {
83          id: row.slug,
84          kind: "page",
85          title: row.title,
86          status,
87          path: row.draft ? null : row.path,
88          publishAt: null,
89          publishedAt: null,
90          updatedAt: row.syncedAt.toISOString(),
91        };
92      });
93      return summaries
94        .filter((s) => !query.status || s.status === query.status)
95        .filter((s) => !needle || s.title.toLowerCase().includes(needle) || s.id.includes(needle));
96    },
97
98    async get(slug) {
99      const found = registered(slug);
100      if (!found) return null;
101      const file = await readFile(env, found.file);
102      if (!file) return null;
103      const row = await env.DB.prepare(`SELECT synced_at FROM pages WHERE slug = ?1`).bind(slug).first<{ synced_at: number }>();
104      const fields = matter(file.content).data;
105      return {
106        id: slug,
107        kind: "page",
108        title: String(fields.title ?? slug),
109        status: statusOf(file.content),
110        path: isDraft(file.content) ? null : found.path,
111        publishAt: null,
112        publishedAt: null,
113        updatedAt: row ? new Date(row.synced_at * 1000).toISOString() : null,
114        format: "markdown",
115        source: file.content,
116        version: file.sha,
117      };
118    },
119
120    // Keeps the stored status, as a post does: a save to a live page edits it live. A page always has its
121    // file, so a save that names no version is a conflict.
122    async saveDraft(slug, input) {
123      const found = target(slug);
124      const file = await readFile(env, found.file);
125      if (input.expectedVersion === null && file) throw new VersionConflictError(file.sha);
126      if (input.expectedVersion !== null && !file) throw new VersionConflictError(null);
127      if (!file) throw new RefusedError(`The file for ${found.path} is missing from the repository, so it cannot be saved.`);
128      return write(slug, input.changeId, withDraft(input.source, isDraft(file.content)), input.expectedVersion);
129    },
130
131    async publish(slug, input) {
132      const stored = await existing(slug);
133      return write(slug, input.changeId, withDraft(input.source ?? stored, false), input.expectedVersion);
134    },
135
136    async unpublish(slug, input) {
137      const stored = await existing(slug);
138      return write(slug, input.changeId, withDraft(stored, true), input.expectedVersion);
139    },
140
141    revisions(slug) {
142      return fileRevisions(env, registered(slug)?.file ?? null);
143    },
144
145    revisionSource(slug, version) {
146      return fileRevisionSource(env, registered(slug)?.file ?? null, version);
147    },
148  };
149}