src/frontmatter.ts

Functions

Imports

It imports no other module of this repo. Imported by src/admin/posts.ts, src/testing.ts.

Source

1// A post's source is YAML frontmatter and a Markdown body. The frontmatter is read as top-level blocks
2// (a key line and the lines that belong to it), and a write replaces only the block it names: every
3// other block, comment and unknown key comes back byte for byte. No YAML parser, so it runs in a
4// Worker and a browser alike. Exported as `@dustinedwards/site-api/frontmatter`.
5
6export type Split = { front: string | null; body: string; open: string; close: string };
7
8const FENCE = /^(---[ \t]*\r?\n)([\s\S]*?)(\r?\n---[ \t]*(?:\r?\n(?:[ \t]*\r?\n)*|$))/;
9
10/** Cuts a source into its frontmatter text, its body and the fences between, so `open + front + close + body` is the source. Blank lines after the closing fence go with the fence, so the body starts at its first line of text. */
11export function splitSource(source: string): Split {
12  const m = FENCE.exec(source);
13  if (!m) return { front: null, body: source, open: "", close: "" };
14  return { front: m[2]!, body: source.slice(m[0].length), open: m[1]!, close: m[3]! };
15}
16
17export function joinSource(s: Split): string {
18  return s.front === null ? s.body : `${s.open}${s.front}${s.close}${s.body}`;
19}
20
21type Block = { key: string | null; lines: string[] };
22
23const KEY = /^([A-Za-z_][\w-]*):(.*)$/;
24
25function blocks(front: string): Block[] {
26  const out: Block[] = [];
27  // A CRLF source reads like an LF one: a key line with a CR on it is still a key line.
28  for (const line of front.split(/\r?\n/)) {
29    const m = KEY.exec(line);
30    if (m) out.push({ key: m[1]!, lines: [line] });
31    else if (out.length > 0) out[out.length - 1]!.lines.push(line);
32    else out.push({ key: null, lines: [line] });
33  }
34  return out;
35}
36
37function unquote(raw: string): string {
38  const v = raw.trim();
39  if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) {
40    try {
41      return JSON.parse(v) as string;
42    } catch {
43      return v.slice(1, -1);
44    }
45  }
46  if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) return v.slice(1, -1).replace(/''/g, "'");
47  return v;
48}
49
50function listOf(block: Block): string[] {
51  const first = KEY.exec(block.lines[0]!)![2]!.trim();
52  if (first.startsWith("[") && first.endsWith("]")) {
53    return first
54      .slice(1, -1)
55      .split(",")
56      .map((t) => unquote(t))
57      .filter(Boolean);
58  }
59  return block.lines
60    .slice(1)
61    .map((l) => /^\s*-\s+(.*)$/.exec(l)?.[1])
62    .filter((v): v is string => v !== undefined)
63    .map(unquote);
64}
65
66/** One top-level key's value as one line of text, or "" when the frontmatter lacks it. */
67export function readKey(front: string | null, key: string): string {
68  if (front === null) return "";
69  const block = blocks(front).find((b) => b.key === key);
70  return block ? unquote(KEY.exec(block.lines[0]!)![2]!) : "";
71}
72
73/** One top-level key's list, flow (`[a, b]`) or block (`- a` lines), unquoted and in order; [] when the frontmatter lacks it. */
74export function readList(front: string | null, key: string): string[] {
75  if (front === null) return [];
76  const block = blocks(front).find((b) => b.key === key);
77  return block ? listOf(block) : [];
78}
79
80/** The tags the frontmatter holds now, in order. */
81export function tagsOf(front: string | null): string[] {
82  return readList(front, "tags").map((t) => t.trim()).filter(Boolean);
83}
84
85/**
86 * The frontmatter with its tags set to exactly this list, and nothing else touched. An empty list is
87 * written as `tags: []`, not removed. A list in block form comes back in flow form.
88 */
89export function setTags(front: string, tags: string[]): string {
90  return setRawKey(front, "tags", `[${tags.map(tagItem).join(", ")}]`);
91}
92
93/** YAML 1.1 reads these plain words as booleans or null, not as the tag. */
94const YAML_WORDS = /^(y|n|yes|no|true|false|on|off|null|~)$/i;
95
96/** A tag as a flow-list item: bare when YAML reads it back as the same string, double-quoted otherwise. */
97function tagItem(tag: string): string {
98  const plain = /^[A-Za-z][\w .+/-]*$/.test(tag) && !/\s$/.test(tag) && !YAML_WORDS.test(tag);
99  return plain ? tag : JSON.stringify(tag);
100}
101
102/** The frontmatter with a top-level key set to a raw value (`draft: true`), added at the end when absent. Every other block is returned as it was. */
103export function setRawKey(front: string, key: string, raw: string): string {
104  return setBlock(front, key, [`${key}: ${raw}`]);
105}
106
107/**
108 * The frontmatter with one top-level key's block replaced by these lines (its key line first), added at
109 * the end when absent, and removed when `lines` is empty. A block that already reads exactly so is left
110 * as it was, and every other block is returned as it was.
111 */
112export function setBlock(front: string, key: string, lines: string[]): string {
113  // Edited as LF and written back in the source's own line ending.
114  const crlf = front.includes("\r\n");
115  const all = blocks(front);
116  const at = all.findIndex((b) => b.key === key);
117  if (at >= 0) {
118    const now = all[at]!.lines;
119    if (now.length === lines.length && now.every((l, i) => l === lines[i])) return front;
120    if (lines.length > 0) all[at] = { key, lines };
121    else all.splice(at, 1);
122  } else if (lines.length > 0) {
123    all.push({ key, lines });
124  } else {
125    return front;
126  }
127  return all.flatMap((b) => b.lines).join(crlf ? "\r\n" : "\n");
128}
129
130// The JSON source format: the front matter a site writes for Carrel when it stores its fields in columns,
131// one `key: <JSON literal>` line per field, so a round trip needs no YAML. A text field may also be written
132// unquoted by hand. `jsonSource` is the one reader and writer, given the site's own field list.
133
134export type JsonFieldKind = "text" | "list" | "flag";
135type JsonValue<K extends JsonFieldKind> = K extends "text" ? string | null : K extends "list" ? string[] : boolean;
136export type JsonValues<F extends Record<string, JsonFieldKind>> = { [K in keyof F]?: JsonValue<F[K]> };
137
138export class JsonSourceError extends Error {
139  constructor(readonly problems: string[]) {
140    super(`The front matter cannot be read:\n${problems.map((p) => `- ${p}`).join("\n")}`);
141    this.name = "JsonSourceError";
142  }
143}
144
145/**
146 * A reader and writer for one site's fields. `write` lists the fields that are not undefined, in the
147 * field list's order, and `blankLine` puts an empty line before the body. `read` returns each key the
148 * source has (a key it leaves out is undefined) and the body, and throws JsonSourceError naming every
149 * problem: an unknown, repeated or malformed key, a value of the wrong kind, or a `required` field that
150 * is missing or blank. With no front matter, the whole source is the body, unless a field is required.
151 */
152export function jsonSource<F extends Record<string, JsonFieldKind>>(fields: F, options: { required?: Array<keyof F & string>; blankLine?: boolean } = {}) {
153  const keys = Object.keys(fields) as Array<keyof F & string>;
154  const required = options.required ?? [];
155  return {
156    write(values: JsonValues<F>, body: string): string {
157      const lines = keys.filter((k) => values[k] !== undefined).map((k) => `${k}: ${JSON.stringify(values[k])}`);
158      return `---\n${lines.join("\n")}\n---\n${options.blankLine ? "\n" : ""}${body}`;
159    },
160    read(source: string): { values: JsonValues<F>; body: string } {
161      const { front, body } = splitSource(source);
162      if (front === null) {
163        if (required.length > 0) throw new JsonSourceError(["The source must start with a front matter block between two --- lines."]);
164        return { values: {}, body: source };
165      }
166      const problems: string[] = [];
167      const values: Record<string, unknown> = {};
168      for (const line of front.split(/\r?\n/)) {
169        if (line.trim() === "") continue;
170        const m = KEY.exec(line);
171        const key = m?.[1];
172        if (!m || !key) problems.push(`This front matter line is not "key: value": ${line.slice(0, 80)}`);
173        else if (!Object.hasOwn(fields, key)) problems.push(`${key} is not a field. The fields are ${keys.join(", ")}.`);
174        else if (key in values) problems.push(`${key} appears twice.`);
175        else values[key] = jsonValue(key, fields[key]!, m[2]!.trim(), problems);
176      }
177      for (const key of required) {
178        const v = values[key];
179        if (v === undefined || v === null || (typeof v === "string" && v.trim() === "")) problems.push(`${key} is required.`);
180      }
181      if (problems.length > 0) throw new JsonSourceError(problems);
182      return { values: values as JsonValues<F>, body };
183    },
184  };
185}
186
187function jsonValue(key: string, kind: JsonFieldKind, raw: string, problems: string[]): unknown {
188  if (kind === "text" && !raw.startsWith('"')) return raw === "" || raw === "null" ? null : raw;
189  let value: unknown;
190  try {
191    value = raw === "" || (kind === "list" && raw === "null") ? (kind === "list" ? [] : false) : JSON.parse(raw);
192  } catch {
193    problems.push(`${key}: the value is not valid JSON.`);
194    return undefined;
195  }
196  if (kind === "text" && typeof value === "string") return value;
197  if (kind === "list" && Array.isArray(value) && value.every((t) => typeof t === "string")) return value.map((t) => t.trim()).filter(Boolean);
198  if (kind === "flag" && typeof value === "boolean") return value;
199  problems.push(`${key} must be ${kind === "text" ? "a string" : kind === "list" ? 'a list of strings, such as ["a", "b"]' : "true or false"}.`);
200  return undefined;
201}