schema.mjs

Functions

Imports

It imports head.mjs. No module of this repo imports it.

Source

1import { absoluteUrl, articleDates } from "./head.mjs";
2
3const CONTEXT = "https://schema.org";
4
5/**
6 * @typedef {Record<string, unknown>} SchemaNode
7 */
8
9/**
10 * The descriptor React Router's `meta` serializes into a `<script type="application/ld+json">`; `headHtml` writes the same.
11 *
12 * @param {SchemaNode} node
13 * @returns {{ "script:ld+json": SchemaNode }}
14 */
15export function jsonLd(node) {
16  return { "script:ld+json": node };
17}
18
19/**
20 * Any schema.org type, with the context added and every empty field dropped: `undefined`, `null`, `""` and `[]` would each
21 * claim a value the page does not have. Person, Organization, Book, Event and the rest are this, with the site's own fields.
22 *
23 * @param {string} type
24 * @param {SchemaNode} fields
25 * @returns {SchemaNode}
26 */
27export function thing(type, fields) {
28  return { "@context": CONTEXT, "@type": type, ...compact(fields) };
29}
30
31/**
32 * Several nodes as one `@graph`, joined by their `@id`s, with the context written once.
33 *
34 * @param {SchemaNode[]} nodes
35 * @returns {SchemaNode}
36 */
37export function graph(nodes) {
38  return {
39    "@context": CONTEXT,
40    "@graph": nodes.map((node) => Object.fromEntries(Object.entries(node).filter(([key]) => key !== "@context"))),
41  };
42}
43
44/**
45 * The site itself. There is no SearchAction unless `searchUrl` is given: one is a promise that the template is a working search.
46 *
47 * @param {{ origin: string, name: string, description?: string, searchUrl?: string, publisher?: SchemaNode }} site
48 *   `searchUrl` holds `{search_term_string}` where the query goes
49 */
50export function website({ origin, name, description, searchUrl, publisher }) {
51  return thing("WebSite", {
52    "@id": `${origin}/#website`,
53    url: origin,
54    name,
55    description,
56    publisher,
57    potentialAction: searchUrl
58      ? { "@type": "SearchAction", target: searchUrl, "query-input": "required name=search_term_string" }
59      : undefined,
60  });
61}
62
63/**
64 * @typedef {object} ArticleInput
65 * @property {string} url
66 * @property {string} headline
67 * @property {string | null} [description]
68 * @property {string | string[]} [image]
69 * @property {Date | number | string | null} [published]
70 * @property {Date | number | string | null} [modified]
71 * @property {string[]} [tags]
72 * @property {SchemaNode} [author]
73 * @property {SchemaNode} [publisher]
74 * @property {string} [type] `Article` unless a subtype fits better (`ScholarlyArticle`, `TechArticle`, `BlogPosting`)
75 */
76
77/**
78 * An article, with its dates from the same `articleDates` the Open Graph tags use.
79 *
80 * @param {ArticleInput} article
81 */
82export function article({ url, headline, description, image, published, modified, tags, author, publisher, type = "Article" }) {
83  const dates = articleDates({ published, modified });
84  return thing(type, {
85    headline,
86    description,
87    image,
88    datePublished: dates.published,
89    dateModified: dates.modified,
90    keywords: tags && tags.length > 0 ? tags.join(", ") : undefined,
91    mainEntityOfPage: { "@type": "WebPage", "@id": url },
92    url,
93    author,
94    publisher,
95  });
96}
97
98/**
99 * @param {string} origin
100 * @param {Array<{ name: string, path: string }>} trail from the home page down
101 */
102export function breadcrumbs(origin, trail) {
103  return thing("BreadcrumbList", {
104    itemListElement: trail.map((crumb, i) => ({
105      "@type": "ListItem",
106      position: i + 1,
107      name: crumb.name,
108      item: absoluteUrl(origin, crumb.path),
109    })),
110  });
111}
112
113/**
114 * @param {string} origin
115 * @param {string} name
116 * @param {Array<{ name: string, path: string }>} items
117 */
118export function itemList(origin, name, items) {
119  return thing("ItemList", {
120    name,
121    numberOfItems: items.length,
122    itemListElement: items.map((item, i) => ({
123      "@type": "ListItem",
124      position: i + 1,
125      name: item.name,
126      url: absoluteUrl(origin, item.path),
127    })),
128  });
129}
130
131/** @param {Array<{ question: string, answer: string }>} faqs */
132export function faqPage(faqs) {
133  return thing("FAQPage", {
134    mainEntity: faqs.map((faq) => ({
135      "@type": "Question",
136      name: faq.question,
137      acceptedAnswer: { "@type": "Answer", text: faq.answer },
138    })),
139  });
140}
141
142/** @param {SchemaNode} fields */
143function compact(fields) {
144  return Object.fromEntries(
145    Object.entries(fields).filter(
146      ([, value]) => value !== undefined && value !== null && value !== "" && !(Array.isArray(value) && value.length === 0),
147    ),
148  );
149}