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

Functions

Imports

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

Source

1// The "dictionary" kind of Carrel's content group (docs/DICTIONARY.md): the entries that open the named
2// Software pages. The id is `dictionary.<key>`, the key being the file's name (`capsid` for
3// content/dictionary/capsid.md). Every write is saveDictionaryEntry, the one dictionary save, so an entry saved
4// through Carrel is validated by the code CI runs, committed, written to D1 and live on the next request with no
5// deploy. An entry's page is a registered path, so what an entry may open is structure and lives in
6// CONTENT_PAGE_PATHS in code; the validator refuses a path that is not one.
7
8import { VersionConflictError } from "@dustinedwards/site-api";
9import type { ContentStatus, ContentSummary, WriteResult } from "@dustinedwards/site-api";
10
11import { listDictionaryRows } from "~/db/dictionary";
12import type { ContentKindHandler } from "~/lib/carrel/content-kinds.server";
13import { asSiteApiError } from "~/lib/carrel/errors.server";
14import { withPublication } from "~/lib/carrel/front-matter-lines";
15import { dictionaryPath, parseDictionaryEntry } from "~/lib/dictionary/parse.mjs";
16import { fileIsDraft, saveDictionaryEntry } from "~/lib/dictionary/save.server";
17import { fileRevisions, fileRevisionSource, readFile } from "~/lib/editor/github.server";
18
19type DictionaryEnv = Env & { GITHUB_TOKEN?: string };
20
21/** A revision's version is a commit sha; an item's own version is the blob sha of its file. */
22
23/** The source with its draft flag set to `draft`, touching no line when it already says so. */
24const withDraft = (raw: string, draft: boolean) => (fileIsDraft(raw) === draft ? raw : withPublication(raw, { draft }));
25
26export function dictionaryHandler(env: DictionaryEnv): ContentKindHandler {
27  /** One write through saveDictionaryEntry as the Carrel actor, answered in the package's terms. */
28  async function write(key: string, changeId: string, raw: string, expectedVersion: string | null): Promise<WriteResult> {
29    try {
30      const saved = await saveDictionaryEntry(env, {
31        key,
32        raw,
33        expectedBlobSha: expectedVersion ?? undefined,
34        isNew: expectedVersion === null,
35        actor: { kind: "carrel", changeId },
36      });
37      return { id: key, version: saved.sourceBlobSha, status: saved.draft ? "draft" : "published", changeId };
38    } catch (error) {
39      // A DictionaryInvalid carries every message the validator gave; asSiteApiError passes them on.
40      return asSiteApiError(env, error, dictionaryPath(key));
41    }
42  }
43
44  /** The stored file for a write that names a version; a version for a missing id is a conflict. */
45  async function existing(key: string): Promise<string> {
46    const file = await readFile(env, dictionaryPath(key));
47    if (!file) throw new VersionConflictError(null);
48    return file.content;
49  }
50
51  return {
52    kind: "dictionary",
53
54    async list(query) {
55      const needle = query.q?.toLowerCase();
56      const summaries: ContentSummary[] = (await listDictionaryRows(env)).map((row) => {
57        const status: ContentStatus = row.draft ? "draft" : "published";
58        return {
59          id: row.key,
60          kind: "dictionary",
61          title: row.term,
62          status,
63          path: row.draft ? null : row.path,
64          publishAt: null,
65          publishedAt: null,
66          updatedAt: row.syncedAt.toISOString(),
67        };
68      });
69      return summaries
70        .filter((s) => !query.status || s.status === query.status)
71        .filter((s) => !needle || s.title.toLowerCase().includes(needle) || s.id.includes(needle));
72    },
73
74    async get(key) {
75      const file = await readFile(env, dictionaryPath(key));
76      if (!file) return null;
77      const row = await env.DB.prepare(`SELECT synced_at FROM dictionary_entries WHERE key = ?1`).bind(key).first<{ synced_at: number }>();
78      const { data } = parseDictionaryEntry({ file: dictionaryPath(key), raw: file.content });
79      const draft = data.draft === true;
80      return {
81        id: key,
82        kind: "dictionary",
83        title: typeof data.term === "string" ? data.term : key,
84        status: draft ? "draft" : "published",
85        path: draft || typeof data.path !== "string" ? null : data.path,
86        publishAt: null,
87        publishedAt: null,
88        updatedAt: row ? new Date(row.synced_at * 1000).toISOString() : null,
89        format: "markdown",
90        source: file.content,
91        version: file.sha,
92      };
93    },
94
95    // Keeps the stored status, as a post does: a save to a live entry edits it live, and a new entry starts as
96    // a draft. First publication is a separate call, which Carrel's key may make.
97    async saveDraft(key, input) {
98      const file = await readFile(env, dictionaryPath(key));
99      if (input.expectedVersion === null && file) throw new VersionConflictError(file.sha);
100      if (input.expectedVersion !== null && !file) throw new VersionConflictError(null);
101      const raw = withDraft(input.source, file ? fileIsDraft(file.content) : true);
102      return write(key, input.changeId, raw, input.expectedVersion);
103    },
104
105    async publish(key, input) {
106      // Read even when source is sent: a version for an id that does not exist is a conflict.
107      const stored = await existing(key);
108      return write(key, input.changeId, withDraft(input.source ?? stored, false), input.expectedVersion);
109    },
110
111    async unpublish(key, input) {
112      const source = await existing(key);
113      return write(key, input.changeId, withDraft(source, true), input.expectedVersion);
114    },
115
116    revisions(key) {
117      return fileRevisions(env, dictionaryPath(key));
118    },
119
120    revisionSource(key, version) {
121      return fileRevisionSource(env, dictionaryPath(key), version);
122    },
123  };
124}