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

Functions

Imports

It imports app/db/registry.ts, app/kb/registry/compile.mjs, app/kb/registry/kinds.mjs, app/kb/registry/save.server.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. Imported by app/lib/carrel/site-adapter.server.ts.

Source

1// The registry kinds of Carrel's /content group (docs/REGISTRY.md): one handler per kind in KINDS (primer, strain,
2// reagent, equipment as they arrive), so Carrel lists and edits each as its own kind. An id is `<kind>.<id>` (the
3// registry encodes it), the id being the item's own, such as `primer.m13-forward`, and the file
4// content/registry/<kind>/<id>.md. Every write is saveRegistryItem, the one path an item reaches the repository by, so
5// an item saved through Carrel is validated by the code CI runs, committed, written to D1 and live on the next request
6// with no deploy. An item has a draft state (a `draft: true` flag, as a page does): saving keeps it, publishing and
7// unpublishing set it.
8//
9// With no kind defined the list is empty and no handler is registered; a kind added to KINDS is served here with no
10// change to this file.
11
12import { RefusedError, VersionConflictError } from "@dustinedwards/site-api";
13import type { ContentStatus, ContentSummary, WriteResult } from "@dustinedwards/site-api";
14import matter from "gray-matter";
15
16import { listRegistryRows } from "~/db/registry";
17import type { ContentKindHandler } from "~/lib/carrel/content-kinds.server";
18import { asSiteApiError } from "~/lib/carrel/errors.server";
19import { withPublication } from "~/lib/carrel/front-matter-lines";
20import { fileRevisions, fileRevisionSource, readFile } from "~/lib/editor/github.server";
21import { ID_PATTERN, registryPath, registrySlug } from "~/kb/registry/compile.mjs";
22import { KINDS, type KindSpec } from "~/kb/registry/kinds.mjs";
23import { saveRegistryItem } from "~/kb/registry/save.server";
24
25type RegistryEnv = Env & { GITHUB_TOKEN?: string };
26
27/** A revision's version is a commit sha; an item's own version is the blob sha of its file. */
28
29const isDraft = (raw: string) => matter(raw, {}).data.draft === true;
30const statusOf = (raw: string): ContentStatus => (isDraft(raw) ? "draft" : "published");
31
32/** One handler per kind. `kinds` is the registry's own unless a test brings its own. */
33export function registryHandlers(env: RegistryEnv, kinds: Readonly<Record<string, KindSpec>> = KINDS): ContentKindHandler[] {
34  return Object.keys(kinds).map((kind) => registryHandler(env, kind, kinds));
35}
36
37function registryHandler(env: RegistryEnv, kind: string, kinds: Readonly<Record<string, KindSpec>>): ContentKindHandler {
38  const noun = kinds[kind]?.singular ?? kind;
39
40  /** An id that is not an item's own shape owns no file, so a read of it is a missing id and never a path to read. */
41  const owns = (id: string) => ID_PATTERN.test(id);
42  const slugOf = (id: string) => registrySlug(kind, id);
43  const fileOf = (id: string) => registryPath(slugOf(id));
44
45  /** One write through saveRegistryItem as the Carrel actor, answered in the package's terms. */
46  async function write(id: string, changeId: string, raw: string, expectedVersion: string | null): Promise<WriteResult> {
47    try {
48      const saved = await saveRegistryItem(env, {
49        slug: slugOf(id),
50        raw,
51        expectedBlobSha: expectedVersion ?? undefined,
52        isNew: expectedVersion === null,
53        actor: { kind: "carrel", changeId },
54        kinds,
55      });
56      return { id, version: saved.sourceBlobSha, status: statusOf(raw), changeId };
57    } catch (error) {
58      // A RegistryInvalid carries every message the validator gave; asSiteApiError passes them on.
59      return asSiteApiError(env, error, fileOf(id));
60    }
61  }
62
63  function target(id: string) {
64    if (!owns(id)) throw new RefusedError(`"${id}" is not a ${noun} id; it is lower-case letters, digits and hyphens, such as m13-forward.`);
65    return fileOf(id);
66  }
67
68  /** The stored file for a write that names a version; a version for a missing file is a conflict. */
69  async function existing(id: string): Promise<string> {
70    const file = await readFile(env, target(id));
71    if (!file) throw new VersionConflictError(null);
72    return file.content;
73  }
74
75  /** The source with its draft flag set to `draft`, touching no line when it already says so. */
76  const withDraft = (raw: string, draft: boolean) => (isDraft(raw) === draft ? raw : withPublication(raw, { draft }));
77
78  return {
79    kind,
80
81    async list(query) {
82      const needle = query.q?.toLowerCase();
83      const summaries: ContentSummary[] = (await listRegistryRows(env))
84        .filter((row) => row.kind === kind)
85        .map((row) => ({
86          id: row.id,
87          kind,
88          title: row.name,
89          status: row.status as ContentStatus,
90          // No page draws an item yet; the pages arrive with the kinds' own changes.
91          path: null,
92          publishAt: null,
93          publishedAt: null,
94          updatedAt: row.syncedAt.toISOString(),
95        }));
96      return summaries
97        .filter((s) => !query.status || s.status === query.status)
98        .filter((s) => !needle || s.title.toLowerCase().includes(needle) || s.id.includes(needle));
99    },
100
101    async get(id) {
102      if (!owns(id)) return null;
103      const file = await readFile(env, fileOf(id));
104      if (!file) return null;
105      const row = await env.DB.prepare(`SELECT name, synced_at FROM registry WHERE kind = ?1 AND id = ?2`)
106        .bind(kind, id)
107        .first<{ name: string; synced_at: number }>();
108      return {
109        id,
110        kind,
111        title: row?.name ?? id,
112        status: statusOf(file.content),
113        path: null,
114        publishAt: null,
115        publishedAt: null,
116        updatedAt: row ? new Date(row.synced_at * 1000).toISOString() : null,
117        format: "markdown",
118        source: file.content,
119        version: file.sha,
120      };
121    },
122
123    // Creates an item (no version) or edits one (its version), keeping its status as a page does.
124    async saveDraft(id, input) {
125      const file = await readFile(env, target(id));
126      if (input.expectedVersion === null && file) throw new VersionConflictError(file.sha);
127      if (input.expectedVersion !== null && !file) throw new VersionConflictError(null);
128      return write(id, input.changeId, input.source, input.expectedVersion);
129    },
130
131    async publish(id, input) {
132      const stored = await existing(id);
133      return write(id, input.changeId, withDraft(input.source ?? stored, false), input.expectedVersion);
134    },
135
136    async unpublish(id, input) {
137      const stored = await existing(id);
138      return write(id, input.changeId, withDraft(stored, true), input.expectedVersion);
139    },
140
141    revisions(id) {
142      return fileRevisions(env, owns(id) ? fileOf(id) : null);
143    },
144
145    revisionSource(id, version) {
146      return fileRevisionSource(env, owns(id) ? fileOf(id) : null, version);
147    },
148  };
149}