app/kb/procedures/library.mjs

Functions

Imports

It imports app/kb/procedures/taxonomy.mjs, app/lib/phage-tools.mjs. Imported by app/components/library-cite.tsx, app/components/library-overview.tsx, app/components/procedure.tsx, app/components/protocol-workflow.tsx, app/kb/libraries.mjs, app/routes/kb-library.tsx, app/routes/kb-library[.csv].ts, app/routes/procedure.tsx, app/routes/procedure[.md].ts, app/routes/protocols.tsx, app/routes/protocols[.csv].ts, app/routes/protocols[.json].ts, app/routes/protocols[.md].ts.

Source

1// The protocol library's one declaration (docs/PROCEDURES.md): the fields a protocol is searched, filtered, sorted
2// and listed by, declared once for Capsomer's catalog. The page, its facets and counts, its sort menu, the CSV and
3// JSON downloads and the markdown twin all read this, so a field is described in exactly one place and a protocol's
4// facts are drawn from its record, never typed again. Pure: the route passes in the records it read from D1.
5
6import { catalogRedirect, defineCatalog, parseCatalogParams, queryCatalog } from "capsomer/behaviour/catalog";
7
8import { TOOLS } from "../../lib/phage-tools.mjs";
9import { CALCULATORS_PATH, COURSES, LIBRARY_PATH, LIBRARY_TABS, METHODS, PHAGE_PIPELINE, courseLabel, methodLabel, NON_STRAIN_ORGANISMS, organismLabel, rememberOrganisms } from "./taxonomy.mjs";
10
11export { LIBRARY_PATH };
12
13/** The kinds a library entry can be: a bench protocol, or a computational method. */
14const KINDS = Object.freeze({ protocol: "Protocol", computational: "Computational method" });
15
16/** @param {string} id */
17const kindLabel = (id) => /** @type {Record<string, string>} */ (KINDS)[id] ?? id;
18
19/**
20 * The one fact worth showing beside a title, drawn from the record and never typed: what it works on (its targets),
21 * else how long it takes. A fact the record does not hold is left out; nothing stands in for it.
22 *
23 * @param {{ targets: string[], time: { total: string | null } }} record
24 */
25export function keyFact(record) {
26  if (record.targets.length > 0) return record.targets.join(", ");
27  if (record.time.total) return record.time.total;
28  return "";
29}
30
31/** How many steps a record has, over all its method sections. @param {import("./render.mjs").ProcedureRecord} record */
32export function stepCount(record) {
33  let n = 0;
34  for (const section of record.sections) {
35    for (const block of section.blocks) if (block.type === "steps") n += block.steps.length;
36  }
37  return n;
38}
39
40/**
41 * The library's rows: the published protocols, each reduced to what the catalog reads. Software how-tos and recipes
42 * have libraries of their own (app/kb/libraries.mjs).
43 *
44 * @param {Array<import("./render.mjs").ProcedureRecord>} records
45 */
46export function libraryItems(records) {
47  for (const r of records) rememberOrganisms(r.organismNames ?? {});
48  return records
49    .filter((r) => r.profile === "protocol")
50    .map((r) => ({
51      slug: r.slug,
52      path: r.path,
53      title: r.title,
54      description: r.description,
55      kind: r.profile,
56      methods: r.methods,
57      organisms: r.organisms,
58      targets: r.targets,
59      courses: r.courses,
60      updated: r.updated ? String(r.updated) : "",
61      version: r.version ? String(r.version) : "",
62      time: r.time.total ? String(r.time.total) : "",
63      steps: stepCount(r),
64      keyFact: keyFact(r),
65      startHere: r.startHere ?? null,
66    }));
67}
68
69/** @typedef {ReturnType<typeof libraryItems>[number]} LibraryItem */
70
71/**
72 * The catalog: fields in the order the facets, columns and sort menu list them. There is no Kind facet while every
73 * entry is a protocol, because a facet of one value filters nothing; it returns with the first computational method.
74 */
75export const LIBRARY = defineCatalog(
76  /** @type {import("capsomer/behaviour/catalog").CatalogDefinition<LibraryItem>} */ ({
77    id: "protocols",
78    noun: ["protocol", "protocols"],
79    basePath: LIBRARY_PATH,
80    itemKey: (p) => p.slug,
81    defaultSort: "title",
82    pageSize: 25,
83    fields: [
84      { key: "title", label: "Protocol", value: (p) => p.title, search: 3, column: { header: "Protocol" }, sort: true },
85      { key: "description", label: "Description", value: (p) => p.description, search: 1 },
86      {
87        key: "method",
88        label: "Method",
89        value: (p) => p.methods,
90        facet: { kind: "many", general: true, label: methodLabel },
91        column: { header: "Method", drop: 1 },
92        search: 1,
93      },
94      {
95        key: "organism",
96        label: "Organism",
97        value: (p) => p.organisms,
98        facet: { kind: "many", label: organismLabel },
99        search: 1,
100      },
101      {
102        key: "target",
103        label: "Target",
104        value: (p) => p.targets,
105        facet: { kind: "many", order: "alpha" },
106        search: 2,
107      },
108      {
109        key: "course",
110        label: "Course",
111        value: (p) => p.courses,
112        facet: { kind: "many", label: courseLabel },
113      },
114      { key: "fact", label: "Key fact", value: (p) => p.keyFact, column: { header: "Key fact", drop: 2 } },
115      { key: "steps", label: "Steps", value: (p) => p.steps, type: "number", sort: true, column: { header: "Steps", align: "end", drop: 2 } },
116      { key: "links", label: "Quick links", value: () => "", column: { header: "Quick links", drop: 2 } },
117      { key: "updated", label: "Updated", value: (p) => p.updated, type: "date", sort: { labels: { asc: "Updated, oldest first", desc: "Updated, newest first" } } },
118    ],
119  }),
120);
121
122/**
123 * The library as rows for a download: every fact the page shows, for the filter state in the address, as ids with
124 * their words, so a machine reads what a person sees. The CSV and the JSON are both this.
125 *
126 * @param {LibraryItem[]} items
127 * @param {URLSearchParams | string} params
128 * @param {string} origin
129 */
130export function libraryRecords(items, params, origin) {
131  const state = parseCatalogParams(LIBRARY, params);
132  return queryCatalog({ ...LIBRARY, pageSize: undefined }, items, { ...state, page: 1 }).rows.map((p) => ({
133    id: p.slug,
134    title: p.title,
135    url: `${origin}${p.path}`,
136    kind: kindLabel(p.kind),
137    methods: p.methods.map(methodLabel),
138    organisms: p.organisms.map(organismLabel),
139    targets: p.targets,
140    courses: p.courses.map(courseLabel),
141    steps: p.steps,
142    time: p.time,
143    version: p.version,
144    updated: p.updated,
145    description: p.description,
146  }));
147}
148
149/**
150 * The same rows as CSV (RFC 4180): a list field is its values joined with "; ". A cell is quoted when it holds a
151 * comma, a quote or a line break.
152 *
153 * @param {Array<Record<string, unknown>>} rows a library's download rows, its own or another base's (app/kb/libraries.mjs)
154 */
155export function libraryCsv(rows) {
156  const columns = Object.keys(rows[0] ?? { id: 1, title: 1, url: 1 });
157  const cellOf = (/** @type {unknown} */ value) => {
158    const text = Array.isArray(value) ? value.join("; ") : String(value ?? "");
159    return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
160  };
161  return `${[columns.join(","), ...rows.map((row) => columns.map((c) => cellOf(row[c])).join(","))].join("\r\n")}\r\n`;
162}
163
164/** One cell of a markdown table. @param {string} text */
165const cell = (text) => text.replaceAll("|", "\\|").replace(/\s+/g, " ").trim();
166
167/**
168 * The twin's table: every protocol with the facts the page shows, drawn from the same items. Links are to the
169 * protocols' own pages, so an agent can follow them.
170 *
171 * @param {LibraryItem[]} items
172 * @param {string} origin
173 */
174export function libraryMarkdown(items, origin) {
175  const head = ["Protocol", "Method", "Organism", "Target", "Course", "Steps", "Updated"];
176  const rows = items.map((p) =>
177    [
178      `[${cell(p.title)}](${origin}${p.path})`,
179      p.methods.map(methodLabel).join(", "),
180      p.organisms.map(organismLabel).join(", "),
181      p.targets.join(", "),
182      p.courses.map(courseLabel).join(", "),
183      String(p.steps),
184      p.updated,
185    ].map((c, i) => (i === 0 ? c : cell(c))),
186  );
187  return [
188    `| ${head.join(" | ")} |`,
189    `| ${head.map(() => "---").join(" | ")} |`,
190    ...rows.map((r) => `| ${r.join(" | ")} |`),
191  ].join("\n");
192}
193
194/** @param {number} n @param {[string, string]} noun */
195export const countOf = (n, noun) => `${n} ${n === 1 ? noun[0] : noun[1]}`;
196
197/**
198 * The overview's counts as a sentence: the one the page's count line and the twin both carry.
199 *
200 * @param {ReturnType<typeof libraryOverview>} overview
201 */
202export function overviewSentence(overview) {
203  const parts = [
204    `${countOf(overview.total, ["protocol", "protocols"])} across ${countOf(overview.methods, ["method", "methods"])}`,
205    overview.organisms > 0 ? `${countOf(overview.organisms, ["organism", "organisms"])}` : "",
206    overview.updated ? `newest updated ${overview.updated}` : "",
207  ].filter(Boolean);
208  return `${parts.join(", ")}.`;
209}
210
211/**
212 * The overview for the twin: the count sentence, the workflow as a list with a link for each stage that has
213 * protocols, and the methods with their counts, so a machine reads what the page shows.
214 *
215 * @param {ReturnType<typeof libraryOverview>} overview
216 * @param {string} origin
217 */
218export function overviewMarkdown(overview, origin) {
219  const noun = /** @type {[string, string]} */ (["protocol", "protocols"]);
220  const stage = (/** @type {(typeof overview.stages)[number]} */ s) =>
221    (s.href ? `- [${s.label}](${origin}${s.href}): ${countOf(s.count, noun)}` : `- ${s.label}`) +
222    s.tools.map((t) => `\n  - [${t.label}](${origin}${t.href})`).join("");
223  return [
224    "## In the library",
225    "",
226    overviewSentence(overview),
227    ...(overview.start.length > 0
228      ? ["", "### Start here", "", ...overview.start.map((p, i) => `${i + 1}. [${p.title}](${origin}${p.href}): ${p.description}`)]
229      : []),
230    "",
231    "### The phage workflow",
232    "",
233    ...overview.stages.map(stage),
234    ...overview.browse.flatMap((group) => [
235      "",
236      `### ${group.title}`,
237      "",
238      ...group.tiles.map((t) => {
239        const about = "about" in t && typeof t.about === "string" ? ` ([about the course](${origin}${t.about}))` : "";
240        return `- [${t.label}](${origin}${t.href}): ${countOf(t.count, noun)}${about}`;
241      }),
242    ]),
243    "",
244    "### Calculators",
245    "",
246    `- [Phage Lab Calculators](${origin}${CALCULATORS_PATH}): ${countOf(calculatorCount(), ["calculator", "calculators"])}`,
247  ].join("\n");
248}
249
250/**
251 * The address of the library narrowed to some values of a facet: the one a person reaches by choosing them there.
252 *
253 * @param {string} key the facet's parameter (method, organism, course)
254 * @param {readonly string[]} values
255 */
256function facetHref(key, values) {
257  return `${LIBRARY_PATH}?${values.map((v) => `${key}=${encodeURIComponent(v)}`).join("&")}`;
258}
259
260/** The library narrowed to some methods. @param {readonly string[]} methods */
261export function methodHref(methods) {
262  return facetHref("method", methods);
263}
264
265/**
266 * A calculator as a link: its page and the name its form carries, both from the one registry. An id the registry does
267 * not know is an error here, not a missing link.
268 *
269 * @param {string} id
270 */
271export function toolLink(id) {
272  const tool = TOOLS[id];
273  if (!tool) throw new Error(`the phage workflow names a calculator "${id}" that phage-tools.mjs does not define`);
274  return { id, label: tool.title, href: tool.path };
275}
276
277/**
278 * What the library says about itself, counted from its rows: how many protocols, over how many methods and
279 * organisms, when the newest changed, a tile for each method that has a protocol, and the phage workflow with the
280 * number of protocols under each stage. Nothing here is typed: a protocol saved changes every figure.
281 *
282 * @param {LibraryItem[]} items
283 */
284export function libraryOverview(items) {
285  /** A tile for each id of a closed list that has a protocol: its words, its count and the library narrowed to it. */
286  const tilesOf = (/** @type {string} */ key, /** @type {Record<string, unknown>} */ list, /** @type {(item: LibraryItem) => readonly string[]} */ valuesOf, /** @type {(id: string) => string} */ label) =>
287    Object.keys(list)
288      .map((id) => ({ id, label: label(id), count: items.filter((p) => valuesOf(p).includes(id)).length, href: facetHref(key, [id]) }))
289      .filter((tile) => tile.count > 0);
290  const tiles = tilesOf("method", METHODS, (p) => p.methods, methodLabel);
291  const browse = [
292    { id: "method", title: "Browse by method", tiles },
293    {
294      id: "course",
295      title: "Browse by course",
296      // A course's tile also names the page that describes it, so the course is one click from its protocols.
297      tiles: tilesOf("course", COURSES, (p) => p.courses, courseLabel).map((tile) => ({ ...tile, about: COURSES[/** @type {keyof typeof COURSES} */ (tile.id)].path })),
298    },
299    { id: "organism", title: "Browse by organism", tiles: tilesOf("organism", Object.fromEntries([...new Set(items.flatMap((p) => p.organisms))].sort((a, b) => Number(Object.hasOwn(NON_STRAIN_ORGANISMS, a)) - Number(Object.hasOwn(NON_STRAIN_ORGANISMS, b)) || organismLabel(a).localeCompare(organismLabel(b), "en")).map((id) => [id, true])), (p) => p.organisms, organismLabel) },
300  ].filter((group) => group.tiles.length > 0);
301  const stages = PHAGE_PIPELINE.map((stage) => {
302    const count = items.filter((p) => p.methods.some((m) => stage.methods.includes(m))).length;
303    const tools = stage.tools.map((id) => toolLink(id));
304    return { id: stage.id, label: stage.label, count, href: count > 0 ? methodHref(stage.methods) : null, tools };
305  });
306  // The protocols that say where to begin, in the position each states (never inferred from anything else).
307  const start = items
308    .filter((p) => p.startHere !== null)
309    .sort((a, b) => /** @type {number} */ (a.startHere) - /** @type {number} */ (b.startHere))
310    .map((p) => ({ slug: p.slug, title: p.title, href: p.path, description: p.description }));
311  const dates = items.map((p) => p.updated).filter(Boolean).sort();
312  return {
313    total: items.length,
314    methods: tiles.length,
315    organisms: new Set(items.flatMap((p) => p.organisms)).size,
316    updated: dates.at(-1) ?? "",
317    tiles,
318    browse,
319    stages,
320    start,
321  };
322}
323
324/**
325 * The tabs over the catalog: All, then each kind of work with the number of protocols in it. A tab is a link, so a
326 * tab, Back and a bookmark all work with no script. The current one is the tab whose methods are exactly the method
327 * filter in the address; All is current while no method is chosen. The registry's kinds (primers, as they land) follow the
328 * calculators as links to their own pages, counted from the registry and never the current tab here.
329 *
330 * @param {LibraryItem[]} items
331 * @param {readonly string[]} chosen the method ids in the address
332 * @param {Array<{ id: string, label: string, count: number, href: string }>} [registry] one entry for each registry kind that has items
333 */
334export function libraryTabs(items, chosen, registry = []) {
335  const same = (/** @type {readonly string[]} */ methods) =>
336    chosen.length === methods.length && methods.every((m) => chosen.includes(m));
337  return [
338    { id: "all", label: "All", count: items.length, href: LIBRARY_PATH, current: chosen.length === 0 },
339    ...LIBRARY_TABS.map((tab) => ({
340      id: tab.id,
341      label: tab.label,
342      count: items.filter((p) => p.methods.some((m) => tab.methods.includes(m))).length,
343      href: methodHref(tab.methods),
344      current: same(tab.methods),
345    })),
346    // The calculators are not protocols, so they are not rows of this catalog: their tab is a link to their own page,
347    // counted from the registry that holds them, and never the current one here.
348    { id: "calculators", label: "Calculators", count: calculatorCount(), href: CALCULATORS_PATH, current: false },
349    ...registry.map((tab) => ({ ...tab, current: false })),
350  ];
351}
352
353/** How many calculator pages there are: the distinct pages the registry's tools sit on. */
354function calculatorCount() {
355  return new Set(Object.values(TOOLS).map((tool) => tool.path)).size;
356}
357
358/**
359 * The address a request should have, or null. The catalog's own redirect sends an address with defaults spelled out,
360 * or in another order, to its one clean address; and it drops every parameter it does not know. The library keeps
361 * the first and leaves the second alone: a tracking parameter or a cache-buster on a library address is served, not
362 * redirected, so a link carrying one still lands on the page it names.
363 *
364 * @param {URL} url
365 */
366export function libraryRedirect(url) {
367  const known = new Set(["q", "sort", "page", ...LIBRARY.fields.filter((f) => f.facet).map((f) => f.key)]);
368  const kept = new URLSearchParams();
369  for (const [key, value] of url.searchParams) if (known.has(key)) kept.append(key, value);
370  const only = new URL(url);
371  only.search = kept.toString();
372  return catalogRedirect(LIBRARY, only);
373}
374
375/**
376 * How to cite the library, from the site's own identity and the library's address: nothing typed here but the shape
377 * of a citation. The date of access is the reader's to add.
378 *
379 * @param {{ name: string, affiliation: string, origin: string }} who
380 */
381export function libraryCitation({ name, affiliation, origin }) {
382  const lab = `${name} Lab`;
383  return {
384    library: `${name}. Protocol library. ${lab}, ${affiliation}. ${origin}${LIBRARY_PATH}`,
385    access: "Add the date you accessed it.",
386    protocol:
387      "To cite one protocol, cite its own page: its title, the lab, the institution, its address and the date you accessed it. " +
388      "A protocol's page names the papers it follows, so cite those for the method itself.",
389  };
390}
391
392/**
393 * The downloads of a view: the CSV and the JSON carry the filter state the address does, so what is downloaded is what is
394 * shown; the markdown twin is always the whole library.
395 *
396 * @param {{ href: () => string }} result the catalog's result, whose `href()` is the clean address of this view
397 */
398export function libraryDownloads(result) {
399  const href = result.href();
400  const query = href.includes("?") ? href.slice(href.indexOf("?")) : "";
401  return { csv: `${LIBRARY_PATH}.csv${query}`, json: `${LIBRARY_PATH}.json${query}`, markdown: `${LIBRARY_PATH}.md` };
402}
403
404/**
405 * The twin's "Download and cite": the same addresses and the same citation the page shows, as absolute links.
406 *
407 * @param {ReturnType<typeof libraryCitation>} citation
408 * @param {string} origin
409 */
410export function citeMarkdown(citation, origin) {
411  return [
412    "## Download and cite",
413    "",
414    `- [CSV](${origin}${LIBRARY_PATH}.csv): every protocol with every fact the table shows; a filtered address gives the filtered rows`,
415    `- [JSON](${origin}${LIBRARY_PATH}.json): the same rows`,
416    `- [Markdown](${origin}${LIBRARY_PATH}.md): this page`,
417    "",
418    "### Cite the library",
419    "",
420    citation.library,
421    "",
422    citation.access,
423    "",
424    citation.protocol,
425  ].join("\n");
426}
427
428/**
429 * Where a protocol sits in the phage workflow, drawn from the same stages the library's strip uses: its stage (the first
430 * whose methods it carries out), the protocols of the nearest earlier and later stage that has any, and the calculators
431 * of its stage. Nothing is typed per protocol: a protocol saved changes its neighbours' links. A protocol outside the
432 * workflow (a PCR primer set) has none, and so does a stage with nothing before or after it.
433 *
434 * @param {LibraryItem[]} items every published library entry
435 * @param {string} path the protocol's own path
436 */
437export function workflowContext(items, path) {
438  const self = items.find((p) => p.path === path);
439  if (!self) return null;
440  const stageOf = (/** @type {LibraryItem} */ p) => PHAGE_PIPELINE.findIndex((stage) => p.methods.some((m) => stage.methods.includes(m)));
441  const at = stageOf(self);
442  if (at === -1) return null;
443  const link = (/** @type {LibraryItem} */ p) => ({ title: p.title, href: p.path });
444  const others = items.filter((p) => p.path !== path);
445  const nearest = (/** @type {number} */ step) => {
446    for (let i = at + step; i >= 0 && i < PHAGE_PIPELINE.length; i += step) {
447      const found = others.filter((p) => stageOf(p) === i);
448      if (found.length > 0) return found.map(link);
449    }
450    return [];
451  };
452  const stage = /** @type {(typeof PHAGE_PIPELINE)[number]} */ (PHAGE_PIPELINE[at]);
453  return { stage: stage.label, before: nearest(-1), after: nearest(1), tools: stage.tools.map(toolLink) };
454}
455
456/**
457 * The same context as lines for the markdown twin, so an agent reads the neighbours a person sees.
458 *
459 * @param {ReturnType<typeof workflowContext>} context
460 * @param {string} origin
461 */
462export function workflowMarkdown(context, origin) {
463  if (!context) return "";
464  const links = (/** @type {Array<{ title: string, href: string }>} */ list) => list.map((p) => `[${p.title}](${origin}${p.href})`).join(", ");
465  return [
466    "## In the phage workflow",
467    "",
468    `Stage: ${context.stage}.`,
469    ...(context.before.length > 0 ? ["", `Before this: ${links(context.before)}.`] : []),
470    ...(context.after.length > 0 ? ["", `After this: ${links(context.after)}.`] : []),
471    ...(context.tools.length > 0 ? ["", `Calculators: ${links(context.tools.map((t) => ({ title: t.label, href: t.href })))}.`] : []),
472  ].join("\n");
473}