app/kb/libraries.mjs

Functions

Imports

It imports app/kb/bases.mjs, app/kb/procedures/library.mjs, app/kb/procedures/taxonomy.mjs, app/kb/procedures/validate.mjs. Imported by app/kb/procedures/route.ts, app/lib/site-urls.server.ts, app/routes.ts, app/routes/kb-library.tsx, app/routes/kb-library[.csv].ts, app/routes/kb-library[.json].ts, app/routes/kb-library[.md].ts.

Source

1// The libraries of the knowledge bases other than Protocols (docs/KNOWLEDGE-BASE.md, step 8): Recipes and Software
2// how-tos, each a catalog over its base's published procedure records, declared once here for Capsomer's catalog as the
3// protocol library is in procedures/library.mjs. The page, its facets, its downloads and its markdown twin all read the
4// declaration, and every fact is drawn from the records, never typed. Pure: the routes pass in the records from D1.
5
6import { catalogRedirect, defineCatalog, parseCatalogParams, queryCatalog } from "capsomer/behaviour/catalog";
7
8import { BASES } from "./bases.mjs";
9import { stepCount } from "./procedures/library.mjs";
10import { courseLabel, methodLabel } from "./procedures/taxonomy.mjs";
11import { HOWTO_TYPES } from "./procedures/validate.mjs";
12
13/** A how-to's type in words: "how-to" is "How-to". @param {string} id */
14export const howtoTypeLabel = (id) => HOWTO_TYPES[/** @type {keyof typeof HOWTO_TYPES} */ (id)] ?? id;
15
16/** @typedef {import("./bases.mjs").KnowledgeBase} KnowledgeBase */
17/** @typedef {import("./procedures/render.mjs").ProcedureRecord} ProcedureRecord */
18
19/** The bases that have a library here: every base but Protocols, whose library is its own (procedures/library.mjs). */
20export const LIBRARY_BASES = Object.freeze(BASES.filter((base) => base.profile !== "protocol"));
21
22/** The base whose library is at `path`, or null. @param {string} path */
23export function baseAtLibrary(path) {
24  return LIBRARY_BASES.find((base) => base.library === path.replace(/\/+$/, "")) ?? null;
25}
26
27/**
28 * The trail to a library: a how-to's under Software, a recipe's on its own. The entry pages' trails extend it.
29 *
30 * @param {KnowledgeBase} base
31 * @returns {Array<[string, string]>}
32 */
33export function libraryTrail(base) {
34  return base.profile === "computational" ? [["Software", "/software"], [base.name, base.library]] : [[base.name, base.library]];
35}
36
37/** A record's times in words: "Prep 15 min, cook 40 min", else its total. @param {ProcedureRecord} r */
38function timeOf(r) {
39  const parts = [r.prepTime ? `prep ${r.prepTime}` : "", r.cookTime ? `cook ${r.cookTime}` : ""].filter(Boolean).join(", ");
40  if (parts) return parts.charAt(0).toUpperCase() + parts.slice(1);
41  return r.time?.total ? String(r.time.total) : "";
42}
43
44/**
45 * The library's rows: the base's published records, each reduced to what its catalog reads.
46 *
47 * @param {KnowledgeBase} base
48 * @param {ProcedureRecord[]} records
49 */
50export function baseItems(base, records) {
51  return records
52    .filter((r) => r.profile === base.profile)
53    .map((r) => ({
54      slug: r.slug,
55      path: r.path,
56      title: r.title,
57      description: r.description,
58      updated: r.updated ? String(r.updated) : "",
59      steps: stepCount(r),
60      time: timeOf(r),
61      // Recipe.
62      servings: r.servings ?? null,
63      cuisine: r.cuisine ? String(r.cuisine) : "",
64      category: r.category ? String(r.category) : "",
65      diet: r.diet ?? [],
66      // Software how-to: tutorial or how-to (S1), empty for a row compiled before it had one.
67      type: r.howtoType ?? "",
68      methods: r.methods ?? [],
69      courses: r.courses ?? [],
70    }));
71}
72
73/** @typedef {ReturnType<typeof baseItems>[number]} BaseItem */
74
75/** The noun a base's entries are counted with: ["recipe", "recipes"]. @param {KnowledgeBase} base @returns {[string, string]} */
76export const nounOf = (base) => [base.singular.toLowerCase(), base.name.toLowerCase()];
77
78// Isolate-wide: a base's catalog is built from its definition, the same for every request.
79/** @type {Map<string, import("capsomer/behaviour/catalog").CatalogDefinition<BaseItem>>} */
80const catalogs = new Map();
81
82/**
83 * A base's catalog: the fields its facets, columns and sort menu list, in that order. A recipe is found by its category,
84 * cuisine and diet; a how-to by the method and course it serves.
85 *
86 * @param {KnowledgeBase} base
87 */
88export function baseCatalog(base) {
89  const known = catalogs.get(base.id);
90  if (known) return known;
91  const title = { key: "title", label: base.singular, value: (/** @type {BaseItem} */ p) => p.title, search: 3, column: { header: base.singular }, sort: true };
92  const description = { key: "description", label: "Description", value: (/** @type {BaseItem} */ p) => p.description, search: 1 };
93  const updated = { key: "updated", label: "Updated", value: (/** @type {BaseItem} */ p) => p.updated, type: "date", sort: { labels: { asc: "Updated, oldest first", desc: "Updated, newest first" } } };
94  const fields =
95    base.profile === "recipe"
96      ? [
97          title,
98          description,
99          { key: "category", label: "Category", value: (/** @type {BaseItem} */ p) => (p.category ? [p.category] : []), facet: { kind: "many", order: "alpha" }, column: { header: "Category", drop: 1 }, search: 1 },
100          { key: "cuisine", label: "Cuisine", value: (/** @type {BaseItem} */ p) => (p.cuisine ? [p.cuisine] : []), facet: { kind: "many", order: "alpha" }, search: 1 },
101          { key: "diet", label: "Diet", value: (/** @type {BaseItem} */ p) => p.diet, facet: { kind: "many", order: "alpha" } },
102          { key: "servings", label: "Servings", value: (/** @type {BaseItem} */ p) => p.servings ?? 0, type: "number", column: { header: "Servings", align: "end", drop: 2 } },
103          { key: "time", label: "Time", value: (/** @type {BaseItem} */ p) => p.time, column: { header: "Time", drop: 2 } },
104          updated,
105        ]
106      : [
107          title,
108          description,
109          { key: "type", label: "Type", value: (/** @type {BaseItem} */ p) => (p.type ? [p.type] : []), facet: { kind: "many", label: howtoTypeLabel }, column: { header: "Type", drop: 1 } },
110          { key: "method", label: "Method", value: (/** @type {BaseItem} */ p) => p.methods, facet: { kind: "many", label: methodLabel }, column: { header: "Method", drop: 1 }, search: 1 },
111          { key: "course", label: "Course", value: (/** @type {BaseItem} */ p) => p.courses, facet: { kind: "many", label: courseLabel } },
112          { key: "steps", label: "Steps", value: (/** @type {BaseItem} */ p) => p.steps, type: "number", sort: true, column: { header: "Steps", align: "end", drop: 2 } },
113          updated,
114        ];
115  const catalog = defineCatalog(
116    /** @type {import("capsomer/behaviour/catalog").CatalogDefinition<BaseItem>} */ ({
117      id: base.id,
118      noun: nounOf(base),
119      basePath: base.library,
120      itemKey: (p) => p.slug,
121      defaultSort: "title",
122      pageSize: 25,
123      fields,
124    }),
125  );
126  catalogs.set(base.id, catalog);
127  return catalog;
128}
129
130/**
131 * The address a request should have, or null: the catalog's own clean address, with unknown parameters (a tracking
132 * tag) served rather than redirected, as the protocol library does.
133 *
134 * @param {KnowledgeBase} base
135 * @param {URL} url
136 */
137export function baseRedirect(base, url) {
138  const catalog = baseCatalog(base);
139  const known = new Set(["q", "sort", "page", ...catalog.fields.filter((f) => f.facet).map((f) => f.key)]);
140  const kept = new URLSearchParams();
141  for (const [key, value] of url.searchParams) if (known.has(key)) kept.append(key, value);
142  const only = new URL(url);
143  only.search = kept.toString();
144  return catalogRedirect(catalog, only);
145}
146
147/**
148 * The library as rows for a download, for the filter state in the address: every fact the page shows, ids with their
149 * words. The CSV and the JSON are both this.
150 *
151 * @param {KnowledgeBase} base
152 * @param {BaseItem[]} items
153 * @param {URLSearchParams | string} params
154 * @param {string} origin
155 */
156export function baseRecords(base, items, params, origin) {
157  const catalog = baseCatalog(base);
158  const state = parseCatalogParams(catalog, params);
159  return queryCatalog({ ...catalog, pageSize: undefined }, items, { ...state, page: 1 }).rows.map((p) => ({
160    id: p.slug,
161    title: p.title,
162    url: `${origin}${p.path}`,
163    ...(base.profile === "recipe"
164      ? { category: p.category, cuisine: p.cuisine, diet: p.diet, servings: p.servings, time: p.time }
165      : { type: p.type ? howtoTypeLabel(p.type) : "", methods: p.methods.map(methodLabel), courses: p.courses.map(courseLabel), steps: p.steps }),
166    updated: p.updated,
167    description: p.description,
168  }));
169}
170
171/** One cell of a markdown table. @param {string} text */
172const cell = (text) => text.replaceAll("|", "\\|").replace(/\s+/g, " ").trim();
173
174/**
175 * The twin's table: every entry with the facts the page shows, linked to its own page. An empty library says so.
176 *
177 * @param {KnowledgeBase} base
178 * @param {BaseItem[]} items
179 * @param {string} origin
180 */
181export function baseMarkdown(base, items, origin) {
182  if (items.length === 0) return `No ${base.name.toLowerCase()} are published yet.`;
183  const recipe = base.profile === "recipe";
184  const head = recipe ? [base.singular, "Category", "Cuisine", "Diet", "Servings", "Time", "Updated"] : [base.singular, "Type", "Method", "Course", "Steps", "Updated"];
185  const rows = items.map((p) =>
186    (recipe
187      ? [`[${cell(p.title)}](${origin}${p.path})`, p.category, p.cuisine, p.diet.join(", "), p.servings === null ? "" : String(p.servings), p.time, p.updated]
188      : [`[${cell(p.title)}](${origin}${p.path})`, p.type ? howtoTypeLabel(p.type) : "", p.methods.map(methodLabel).join(", "), p.courses.map(courseLabel).join(", "), String(p.steps), p.updated]
189    ).map((c, i) => (i === 0 ? c : cell(c))),
190  );
191  return [`| ${head.join(" | ")} |`, `| ${head.map(() => "---").join(" | ")} |`, ...rows.map((r) => `| ${r.join(" | ")} |`)].join("\n");
192}
193
194/** The downloads of a view, carrying its filter state; the twin is always the whole library. @param {KnowledgeBase} base @param {{ href: () => string }} result */
195export function baseDownloads(base, result) {
196  const href = result.href();
197  const query = href.includes("?") ? href.slice(href.indexOf("?")) : "";
198  return { csv: `${base.library}.csv${query}`, json: `${base.library}.json${query}`, markdown: `${base.library}.md` };
199}
200
201/** How to cite the library, from the site's identity and the library's address. @param {KnowledgeBase} base @param {{ name: string, affiliation: string, origin: string }} who */
202export function baseCitation(base, { name, affiliation, origin }) {
203  return {
204    library: `${name}. ${base.name}. ${name} Lab, ${affiliation}. ${origin}${base.library}`,
205    access: "Add the date you accessed it.",
206    protocol: `To cite one ${base.singular.toLowerCase()}, cite its own page: its title, the lab, the institution, its address and the date you accessed it.`,
207  };
208}