app/lib/carrel/content-kinds.server.ts

Functions

Imports

It imports app/lib/carrel/content-id.mjs. Imported by app/lib/carrel/cv-handler.server.ts, app/lib/carrel/dictionary-handler.server.ts, app/lib/carrel/document-handler.server.ts, app/lib/carrel/page-handler.server.ts, app/lib/carrel/phage-handler.server.ts, app/lib/carrel/procedure-handler.server.ts, app/lib/carrel/publication-handler.server.ts, app/lib/carrel/registry-handler.server.ts, app/lib/carrel/roster-handler.server.ts, app/lib/carrel/site-adapter.server.ts.

Source

1// The kind registry behind Carrel's /content group. site-api's contract has one id space and a free-form
2// `kind` string on a summary, so each content kind (post, publication, page, cv) is a handler that works in
3// its own slugs, and this module is the only place that turns a slug into a contract id and back.
4
5import { NotFoundError, RefusedError } from "@dustinedwards/site-api";
6import type {
7  ContentAdapter,
8  ContentDoc,
9  ContentSummary,
10  ListQuery,
11  PreviewInput,
12  PublishInput,
13  Revision,
14  SaveDraftInput,
15  ScheduleInput,
16  UnpublishInput,
17  WriteResult,
18} from "@dustinedwards/site-api";
19
20import { DEFAULT_KIND, decodeContentId, encodeContentId } from "./content-id.mjs";
21
22/**
23 * One kind's side of the content group. Every id a handler takes or returns is its own slug; the
24 * registry encodes it on the way out.
25 */
26export interface ContentKindHandler {
27  kind: string;
28  /** Every item of the kind matching q and status; the registry merges kinds and pages the result. */
29  list(query: Pick<ListQuery, "q" | "status">): Promise<ContentSummary[]>;
30  get(slug: string): Promise<ContentDoc | null>;
31  saveDraft(slug: string, input: SaveDraftInput): Promise<WriteResult>;
32  publish(slug: string, input: PublishInput): Promise<WriteResult>;
33  schedule?(slug: string, input: ScheduleInput): Promise<WriteResult>;
34  unpublish(slug: string, input: UnpublishInput): Promise<WriteResult>;
35  revisions(slug: string): Promise<Revision[] | null>;
36  revisionSource(slug: string, version: string): Promise<string | null>;
37  /**
38   * Deletes the item and whatever must follow it as one unit (v0.3.0). Throws NotFoundError for a missing
39   * item, VersionConflictError for a stale version and RefusedError when the site's rules refuse. A kind
40   * without it cannot be deleted from Carrel.
41   */
42  delete?(slug: string, input: { expectedVersion: string; changeId: string }): Promise<void>;
43  /** The page the item would publish; `slug` is null for an unsaved new item. */
44  preview?(slug: string | null, input: PreviewInput): Promise<string>;
45}
46
47export type ContentRegistry = {
48  adapter: ContentAdapter;
49  render(input: PreviewInput): Promise<string>;
50};
51
52export function contentRegistry(handlers: ContentKindHandler[]): ContentRegistry {
53  const byKind = new Map(handlers.map((h) => [h.kind, h]));
54  if (byKind.size !== handlers.length) throw new Error("two content kind handlers share a kind");
55
56  /** The handler and slug for an id, or null when no registered kind owns it. */
57  const route = (id: string) => {
58    const { kind, slug } = decodeContentId(id);
59    const handler = byKind.get(kind);
60    return handler ? { handler, slug } : null;
61  };
62
63  const encoded = <T extends { id: string }>(kind: string, value: T): T => ({
64    ...value,
65    id: encodeContentId(kind, value.id),
66  });
67
68  /** A write for an id no kind owns is a missing id, which the contract answers as a null version. */
69  const owner = (id: string) => {
70    const found = route(id);
71    if (!found) throw new RefusedError(`No content kind owns the id ${id}.`);
72    return found;
73  };
74
75  const adapter: ContentAdapter = {
76    async list(query) {
77      const lists = await Promise.all(
78        handlers.map(async (h) =>
79          (await h.list({ q: query.q, status: query.status })).map((s) => encoded(h.kind, s)),
80        ),
81      );
82      const matching = lists.flat();
83      const start = query.cursor && /^\d+$/.test(query.cursor) ? Number(query.cursor) : 0;
84      const end = start + query.limit;
85      return {
86        items: matching.slice(start, end),
87        nextCursor: end < matching.length ? String(end) : null,
88      };
89    },
90
91    async get(id) {
92      const found = route(id);
93      if (!found) return null;
94      const doc = await found.handler.get(found.slug);
95      return doc ? encoded(found.handler.kind, doc) : null;
96    },
97
98    async saveDraft(id, input) {
99      const { handler, slug } = owner(id);
100      return encoded(handler.kind, await handler.saveDraft(slug, input));
101    },
102
103    async publish(id, input) {
104      const { handler, slug } = owner(id);
105      return encoded(handler.kind, await handler.publish(slug, input));
106    },
107
108    async schedule(id, input) {
109      const { handler, slug } = owner(id);
110      if (!handler.schedule) throw new RefusedError(`A ${handler.kind} cannot be scheduled; publish it now.`);
111      return encoded(handler.kind, await handler.schedule(slug, input));
112    },
113
114    async unpublish(id, input) {
115      const { handler, slug } = owner(id);
116      return encoded(handler.kind, await handler.unpublish(slug, input));
117    },
118
119    async revisions(id) {
120      const found = route(id);
121      return found ? found.handler.revisions(found.slug) : null;
122    },
123
124    async revisionSource(id, version) {
125      const found = route(id);
126      return found ? found.handler.revisionSource(found.slug, version) : null;
127    },
128
129    async delete(id, input) {
130      const found = route(id);
131      if (!found) throw new NotFoundError(`No content kind owns the id ${id}.`);
132      if (!found.handler.delete) {
133        throw new RefusedError(`A ${found.handler.kind} cannot be deleted from Carrel.`);
134      }
135      await found.handler.delete(found.slug, input);
136    },
137  };
138
139  return {
140    adapter,
141    async render(input) {
142      // No id is a new, unsaved item, and only a post can be previewed without one.
143      const found = input.id === undefined ? null : route(input.id);
144      const target = input.id === undefined ? byKind.get(DEFAULT_KIND) : found?.handler;
145      if (!target?.preview) throw new RefusedError("This kind of content has no preview.");
146      return target.preview(found ? found.slug : null, input);
147    },
148  };
149}