app/kb/registry/catalog.mjs

Functions

Imports

It imports app/kb/registry/align.mjs, app/kb/registry/kinds.mjs, app/kb/registry/primer.mjs, app/kb/registry/strain.mjs, app/kb/registry/tm.mjs, app/lib/phages/compile.mjs, app/lib/primers.mjs. Imported by app/components/lab.tsx, app/components/procedure-materials.tsx, app/kb/admin.mjs, app/kb/editor.server.ts, app/kb/procedures/compile.mjs, app/kb/procedures/render.mjs, app/kb/registry/search-inputs.mjs, app/kb/search-bases.mjs, app/lib/site-urls.server.ts, app/routes/lab.kind.tsx, app/routes/lab.tsx, app/routes/lab[.md].ts, app/routes/protocols.tsx.

Source

1// How the registry reads on the site (docs/REGISTRY.md): its addresses, the master inventory over every kind and the
2// phages, and each kind's own catalog, declared once for Capsomer's catalog so the page, its facets and counts, its
3// sort menu and the markdown twin all read one declaration. Pure: the routes hand it the rows they read from D1.
4//
5// Nothing is typed again here. A primer's length, GC content, reverse complement and Tm come from its sequence, the
6// protocols that use it are found by that sequence, and a phage in the inventory is read from the phages table, never
7// copied into the registry.
8
9import { defineCatalog } from "capsomer/behaviour/catalog";
10
11import { HOSTS } from "../../lib/phages/compile.mjs";
12import { reverseComplement } from "../../lib/primers.mjs";
13import { KINDS } from "./kinds.mjs";
14import { MAX_MISMATCHES, pairProducts, placePrimer } from "./align.mjs";
15import { missingReason, primerFacts, stated } from "./primer.mjs";
16import { designationOf } from "./strain.mjs";
17import { NEB_TM_CALCULATOR, TM_CONDITIONS, annealingSentence, tmStatement } from "./tm.mjs";
18
19/** The master inventory, and the root every kind's page sits under. */
20export const LAB_PATH = "/research/lab";
21
22/** The kind's page, from its plural: /research/lab/primers. @param {string} kind @param {Record<string, import("./kinds.mjs").KindSpec>} [kinds] */
23export function kindPath(kind, kinds = KINDS) {
24  return `${LAB_PATH}/${kinds[kind]?.plural ?? kind}`;
25}
26
27/** An item's page: /research/lab/primers/lco1490. @param {string} kind @param {string} id @param {Record<string, import("./kinds.mjs").KindSpec>} [kinds] */
28export function itemPath(kind, id, kinds = KINDS) {
29  return `${kindPath(kind, kinds)}/${id}`;
30}
31
32/**
33 * The kind a URL segment names (its plural), or null.
34 *
35 * @param {string} segment
36 * @param {Readonly<Record<string, import("./kinds.mjs").KindSpec>>} [kinds]
37 */
38export function kindFromSegment(segment, kinds = KINDS) {
39  return Object.keys(kinds).find((kind) => kinds[kind]?.plural === segment) ?? null;
40}
41
42
43/**
44 * The library's tabs for the registry: one for each kind that has a published item, linking to the kind's page, in the
45 * order the kinds are defined. A kind with no item has no tab, so none points at an empty page.
46 *
47 * @param {import("./kinds.mjs").RegistryItem[]} items
48 * @param {Readonly<Record<string, import("./kinds.mjs").KindSpec>>} [kinds]
49 */
50export function registryTabs(items, kinds = KINDS) {
51  return Object.keys(kinds).flatMap((kind) => {
52    const count = items.filter((item) => item.kind === kind).length;
53    const plural = kinds[kind]?.plural ?? kind;
54    return count === 0 ? [] : [{ id: plural, label: plural.charAt(0).toUpperCase() + plural.slice(1), count, href: kindPath(kind, kinds) }];
55  });
56}
57
58/* ------------------------------------------------------------------------------------------------ primers */
59
60/**
61 * A primer as the pages read it: the record's own fields, the literature as read (and what could not be), and what is
62 * computed: from its sequence, its length, GC content, Tm and reverse complement; from its reference, its placement; and by
63 * comparison, whether its sequence matches the one the paper prints. Nothing computed is stored.
64 *
65 * @param {import("./kinds.mjs").RegistryItem} item
66 */
67export function primerRow(item) {
68  const f = /** @type {Record<string, unknown>} */ (item.fields);
69  const sequence = stated(f.sequence);
70  const reference = stated(f.reference);
71  const facts = sequence ? primerFacts(sequence) : { length: null, gcPercent: null, tm: null };
72  const printed = stated(f.published_sequence);
73  return {
74    id: item.id,
75    path: itemPath("primer", item.id),
76    name: item.name,
77    sequence,
78    reverseComplement: sequence && /^[ACGT]+$/.test(sequence) ? reverseComplement(sequence) : null,
79    direction: stated(f.direction),
80    target: stated(f.target),
81    set: stated(f.set),
82    reference,
83    // Where it binds the reference, computed: null when it has no reference or binds nowhere within the mismatch limit.
84    placement: sequence && reference ? placePrimer(sequence, reference) : null,
85    // What the literature says, as read. Each `...Missing` is the reason it could not be found, shown so it is not hunted for.
86    publishedIn: stated(f.published_in),
87    publishedInMissing: missingReason(f.published_in),
88    publishedDoi: stated(f.published_doi),
89    publishedUrl: stated(f.published_url),
90    publishedName: stated(f.published_name),
91    publishedNameMissing: missingReason(f.published_name),
92    publishedSequence: printed,
93    publishedSequenceMissing: missingReason(f.published_sequence),
94    publishedProduct: stated(f.published_product),
95    publishedProductMissing: missingReason(f.published_product),
96    // A comparison, never a field: null when the paper's sequence was not read, true when the stored one equals it.
97    matchesPublished: printed && sequence ? printed === sequence : null,
98    length: facts.length,
99    gcPercent: facts.gcPercent,
100    tm: facts.tm,
101    draft: item.status === "draft",
102  };
103}
104
105/** @typedef {ReturnType<typeof primerRow>} PrimerRow */
106
107/**
108 * The primers as rows with their pair's product computed, which a row alone cannot say: the product needs both primers of a
109 * set, placed on their one reference.
110 *
111 * @param {import("./kinds.mjs").RegistryItem[]} items
112 */
113export function primerRows(items) {
114  const rows = items.filter((item) => item.kind === "primer").map(primerRow);
115  return rows.map((row) => ({ ...row, product: pairProduct(row, rows) }));
116}
117
118/** @typedef {ReturnType<typeof primerRows>[number]} PrimerListRow */
119
120const DIRECTION_LABELS = /** @type {Record<string, string>} */ ({ forward: "Forward", reverse: "Reverse", probe: "Probe" });
121
122/**
123 * One line of a pair's product as the catalog and the twin show it: "281 bp", and "at 2 sites" when the pair binds twice (the
124 * two LTRs of a provirus), or each size when the sites differ.
125 *
126 * @param {{ products: Array<{ length: number }> } | null} pair
127 */
128export function productText(pair) {
129  if (!pair) return null;
130  const sizes = [...new Set(pair.products.map((p) => p.length))];
131  const text = sizes.map((s) => `${s} bp`).join(" or ");
132  return pair.products.length > 1 && sizes.length === 1 ? `${text} at ${pair.products.length} sites` : text;
133}
134
135/** The primers catalog: the columns a primer is read by, which are its own and not a protocol's. */
136export const PRIMERS = defineCatalog(
137  /** @type {import("capsomer/behaviour/catalog").CatalogDefinition<PrimerListRow>} */ ({
138    id: "primers",
139    noun: ["primer", "primers"],
140    basePath: kindPath("primer"),
141    itemKey: (p) => p.id,
142    defaultSort: "name",
143    pageSize: 25,
144    fields: [
145      { key: "name", label: "Primer", value: (p) => p.name, search: 3, column: { header: "Primer" }, sort: true },
146      { key: "sequence", label: "Sequence (5′ to 3′)", value: (p) => p.sequence ?? "", search: 2, column: { header: "Sequence (5′ to 3′)", drop: 1 } },
147      {
148        key: "direction",
149        label: "Direction",
150        value: (p) => p.direction,
151        facet: { kind: "many", general: true, label: (value) => DIRECTION_LABELS[value] ?? value },
152        column: { header: "Direction", drop: 2 },
153      },
154      { key: "target", label: "Target", value: (p) => p.target, facet: { kind: "many", order: "alpha" }, search: 2, column: { header: "Target", drop: 1 } },
155      { key: "set", label: "Set", value: (p) => p.set, search: 1 },
156      { key: "length", label: "Length (nt)", value: (p) => p.length, type: "number", sort: true, column: { header: "Length (nt)", align: "end", drop: 2 } },
157      { key: "tm", label: "Tm estimate (°C)", value: (p) => p.tm, type: "number", sort: true, column: { header: "Tm estimate (°C)", align: "end", drop: 2 } },
158      { key: "product", label: "Product (computed)", value: (p) => productText(p.product), column: { header: "Product (computed)", drop: 2 } },
159    ],
160  }),
161);
162
163/**
164 * The primer in the same set that pairs with this one: the other direction, in the same set. Null when it has no set or
165 * the set holds no mate.
166 *
167 * @param {PrimerRow} primer
168 * @param {PrimerRow[]} primers
169 */
170export function mateOf(primer, primers) {
171  if (!primer.set) return null;
172  return primers.find((p) => p.id !== primer.id && p.set === primer.set && p.direction !== primer.direction) ?? null;
173}
174
175/**
176 * The product the pair of a primer makes on its reference, computed from the two sequences and the reference they share
177 * (align.mjs), so it is stored nowhere and shown on both primers. Null when the primer has no mate, the pair shares no
178 * reference, or either primer does not bind it.
179 *
180 * @param {PrimerRow} primer
181 * @param {PrimerRow[]} primers
182 */
183export function pairProduct(primer, primers) {
184  const mate = mateOf(primer, primers);
185  if (!mate || !primer.sequence || !mate.sequence || !primer.reference || primer.reference !== mate.reference) return null;
186  const forward = primer.direction === "forward" ? primer : mate;
187  const reverse = primer.direction === "forward" ? mate : primer;
188  if (forward.direction !== "forward" || reverse.direction !== "reverse" || !forward.sequence || !reverse.sequence) return null;
189  return pairProducts(forward.sequence, reverse.sequence, primer.reference);
190}
191
192/**
193 * The protocols that use a primer: each published protocol names its primers by id (and carries the registry's facts for
194 * them), so the use is read from the protocols and never listed on the primer.
195 *
196 * @param {PrimerRow} primer
197 * @param {Array<{ path: string, title: string, primers: Array<{ id: string }> }>} protocols
198 */
199export function protocolsUsing(primer, protocols) {
200  return protocols
201    .filter((protocol) => protocol.primers.some((p) => p.id === primer.id))
202    .map((protocol) => ({ path: protocol.path, title: protocol.title }));
203}
204
205/* ------------------------------------------------------------------------------------------------ strains */
206
207/**
208 * A strain as the pages read it: the record's own fields, and what is computed from elsewhere: its designation (from its
209 * fields), and the phages isolated on it, read from the phages table by the host key that is the strain's own id. Nothing
210 * computed is stored, so a phage added to the table is on the strain's page with no edit to the strain.
211 *
212 * @param {import("./kinds.mjs").RegistryItem} item
213 * @param {Array<{ name: string, year: number, host: string | null }>} [phages] every phage, from the phages table
214 */
215export function strainRow(item, phages = []) {
216  const f = /** @type {Record<string, unknown>} */ (item.fields);
217  const isolated = phages.filter((phage) => phage.host === item.id).sort((a, b) => a.year - b.year || a.name.localeCompare(b.name, "en", { numeric: true }));
218  const years = isolated.map((phage) => phage.year);
219  return {
220    id: item.id,
221    path: itemPath("strain", item.id),
222    name: item.name,
223    organism: stated(f.organism),
224    strain: stated(f.strain),
225    designation: designationOf(f),
226    collection: stated(f.collection),
227    collectionNumber: stated(f.collection_number),
228    guideUrl: stated(f.guide_url),
229    biosafetyLevel: stated(f.biosafety_level),
230    biosafetyLevelMissing: missingReason(f.biosafety_level),
231    phages: isolated.map((phage) => ({ name: phage.name, year: phage.year, path: `/research/phages#${phage.name.toLowerCase()}` })),
232    firstYear: years.length ? Math.min(...years) : null,
233    lastYear: years.length ? Math.max(...years) : null,
234    draft: item.status === "draft",
235  };
236}
237
238/** @typedef {ReturnType<typeof strainRow>} StrainRow */
239
240/** The strains as rows, each with the phages isolated on it. @param {import("./kinds.mjs").RegistryItem[]} items @param {Array<{ name: string, year: number, host: string | null }>} phages */
241export function strainRows(items, phages) {
242  return items.filter((item) => item.kind === "strain").map((item) => strainRow(item, phages));
243}
244
245/** The strains catalog: the columns a strain is read by. */
246export const STRAINS = defineCatalog(
247  /** @type {import("capsomer/behaviour/catalog").CatalogDefinition<StrainRow>} */ ({
248    id: "strains",
249    noun: ["strain", "strains"],
250    basePath: kindPath("strain"),
251    itemKey: (s) => s.id,
252    defaultSort: "name",
253    pageSize: 25,
254    fields: [
255      { key: "name", label: "Strain", value: (s) => s.name, search: 3, column: { header: "Strain" }, sort: true },
256      { key: "organism", label: "Organism", value: (s) => s.organism, facet: { kind: "many", order: "alpha" }, search: 2, column: { header: "Organism", drop: 1 } },
257      { key: "collection", label: "Collection", value: (s) => s.collection, facet: { kind: "many", order: "alpha" }, search: 1, column: { header: "Collection", drop: 2 } },
258      { key: "number", label: "Collection number", value: (s) => s.collectionNumber, search: 2, column: { header: "Collection number", drop: 2 } },
259      { key: "phages", label: "Phages isolated", value: (s) => s.phages.length, type: "number", sort: true, column: { header: "Phages isolated", align: "end", drop: 1 } },
260    ],
261  }),
262);
263
264/**
265 * The protocols that use a strain: each published protocol names its host strains by id, so the use is read from the
266 * protocols and never listed on the strain.
267 *
268 * @param {{ id: string }} strain
269 * @param {Array<{ path: string, title: string, hostStrains?: Array<{ id: string }> }>} protocols
270 */
271export function protocolsUsingStrain(strain, protocols) {
272  return protocols
273    .filter((protocol) => (protocol.hostStrains ?? []).some((s) => s.id === strain.id))
274    .map((protocol) => ({ path: protocol.path, title: protocol.title }));
275}
276
277/** The span of years the phages on a strain were isolated in, in words: "2018", or "2018 to 2025". @param {StrainRow} strain */
278export function phageYearsText(strain) {
279  if (strain.firstYear === null) return null;
280  return strain.firstYear === strain.lastYear ? String(strain.firstYear) : `${strain.firstYear} to ${strain.lastYear}`;
281}
282
283/** The strains as a markdown table for the twin. @param {StrainRow[]} strains @param {string} origin */
284export function strainsMarkdown(strains, origin) {
285  const lines = strains.map(
286    (s) => `| [${cell(s.name)}](${origin}${s.path}) | ${cell(s.organism)} | ${cell(s.collection)} | ${cell(s.collectionNumber)} | ${s.phages.length} |`,
287  );
288  return [
289    "| Strain | Organism | Collection | Collection number | Phages isolated |",
290    "| --- | --- | --- | --- | --- |",
291    ...lines,
292  ].join("\n");
293}
294
295/**
296 * One strain as markdown for the twin: the same facts the page states, with a fact nobody has set said with its reason.
297 *
298 * @param {StrainRow} strain
299 * @param {Array<{ path: string, title: string }>} usedBy
300 * @param {string} origin
301 */
302export function strainMarkdown(strain, usedBy, origin) {
303  const years = phageYearsText(strain);
304  const lines = [
305    strain.organism ? `- Organism: ${strain.organism}` : "",
306    strain.strain ? `- Strain: ${strain.strain}` : "",
307    strain.collection && strain.collectionNumber ? `- Collection: ${strain.collection} ${strain.collectionNumber}` : "",
308    strain.guideUrl ? `- SEA-PHAGES Guide page: ${strain.guideUrl}` : "",
309    `- Biosafety level: ${strain.biosafetyLevel ?? `not found (${strain.biosafetyLevelMissing ?? "not recorded"})`}`,
310    "",
311    "## Phages isolated on it",
312    "",
313    strain.phages.length === 0
314      ? "No phage in the lab's table names this host."
315      : `${strain.phages.length} phage${strain.phages.length === 1 ? "" : "s"}, found ${years}, counted from the phages table.`,
316    "",
317    ...strain.phages.map((phage) => `- [${phage.name}](${origin}${phage.path}), ${phage.year}`),
318    "",
319    ...usedBy.map((protocol) => `- Used in: [${protocol.title}](${origin}${protocol.path})`),
320  ];
321  return `# ${strain.name}\n\n${lines.join("\n").replace(/\n{3,}/g, "\n\n").trim()}\n`;
322}
323
324/* ------------------------------------------------------------------------------------------------ reagents */
325
326/**
327 * Whether a kind has a page for each item. Every kind does today (docs/KNOWLEDGE-BASE.md, A1); a kind that is only ever one table
328 * says `itemPages: false`.
329 *
330 * @param {string} kind
331 * @param {Readonly<Record<string, import("./kinds.mjs").KindSpec>>} [kinds]
332 */
333export function hasItemPage(kind, kinds = KINDS) {
334  return kinds[kind]?.itemPages !== false;
335}
336
337/**
338 * Where a procedure with the recipe profile is: a recipe's address is under /recipes (PROFILE_ROOTS in the procedure validator).
339 *
340 * @param {string} slug
341 */
342function recipePath(slug) {
343  return `/recipes/${slug}`;
344}
345
346/**
347 * What the protocols use of a reagent, read from the protocols that name it on one of their materials (`reagent: <id>`): the
348 * protocols only, since a protocol's own amounts, stocks and finals are shown in that protocol's table. Nothing is stored on the
349 * reagent, so a protocol that names it later is listed with no edit to the record.
350 *
351 * @param {string} id
352 * @param {Array<{ path: string, title: string, materials?: Array<{ reagent?: { id: string } | null }> }>} protocols
353 */
354export function reagentUses(id, protocols) {
355  return protocols
356    .filter((protocol) => (protocol.materials ?? []).some((m) => m.reagent?.id === id))
357    .map((protocol) => ({ path: protocol.path, title: protocol.title }));
358}
359
360/**
361 * A reagent as the pages read it: the record's own fields and the protocols that use it, computed from the protocols. A reagent is
362 * bought (a supplier and a catalog number, each stated or a gap with its reason) or prepared in the lab (a recipe, which is a
363 * procedure with the recipe profile, or a gap with its reason).
364 *
365 * @param {import("./kinds.mjs").RegistryItem} item
366 * @param {Parameters<typeof reagentUses>[1]} [protocols]
367 */
368export function reagentRow(item, protocols = []) {
369  const f = /** @type {Record<string, unknown>} */ (item.fields);
370  const prepared = f.prepared_in_lab === true;
371  const recipe = stated(f.recipe);
372  return {
373    id: item.id,
374    name: item.name,
375    path: itemPath("reagent", item.id),
376    abbreviation: stated(f.abbreviation),
377    contents: stated(f.contents),
378    preparedInLab: prepared,
379    supplier: stated(f.supplier),
380    supplierMissing: missingReason(f.supplier),
381    catalogNumber: stated(f.catalog_number),
382    catalogNumberMissing: missingReason(f.catalog_number),
383    productUrl: stated(f.product_url),
384    recipe,
385    recipePath: recipe ? recipePath(recipe) : null,
386    recipeMissing: missingReason(f.recipe),
387    uses: reagentUses(item.id, protocols),
388    draft: item.status === "draft",
389  };
390}
391
392/** @typedef {ReturnType<typeof reagentRow>} ReagentRow */
393
394/** The reagents as rows, each with the protocols that use it. @param {import("./kinds.mjs").RegistryItem[]} items @param {Parameters<typeof reagentUses>[1]} protocols */
395export function reagentRows(items, protocols) {
396  return items.filter((item) => item.kind === "reagent").map((item) => reagentRow(item, protocols));
397}
398
399/** The name as the table shows it: the abbreviation or what it is made of beside it, where a protocol states one. @param {ReagentRow} r */
400export function reagentLabel(r) {
401  const more = [r.abbreviation, r.contents].filter(Boolean).join("; ");
402  return more ? `${r.name} (${more})` : r.name;
403}
404
405/** The "supplier" cell in words: who makes a bought reagent, or that the lab prepares it. @param {ReagentRow} r */
406export function reagentSource(r) {
407  return r.preparedInLab ? "Prepared in lab" : r.supplier;
408}
409
410/** The reagents catalog: the one table, with the columns a reagent is read by. */
411export const REAGENTS = defineCatalog(
412  /** @type {import("capsomer/behaviour/catalog").CatalogDefinition<ReagentRow>} */ ({
413    id: "reagents",
414    noun: ["reagent", "reagents"],
415    basePath: kindPath("reagent"),
416    itemKey: (r) => r.id,
417    defaultSort: "name",
418    pageSize: 50,
419    fields: [
420      { key: "name", label: "Reagent", value: (r) => reagentLabel(r), search: 3, column: { header: "Reagent" }, sort: true },
421      { key: "supplier", label: "Supplier", value: (r) => reagentSource(r), facet: { kind: "many", order: "alpha" }, search: 1, column: { header: "Supplier", drop: 1 } },
422      { key: "number", label: "Catalog number", value: (r) => r.catalogNumber, search: 2, column: { header: "Catalog number", drop: 1 } },
423      { key: "link", label: "Link", value: (r) => r.productUrl ?? r.recipePath, column: { header: "Link", drop: 2 } },
424      { key: "protocols", label: "Protocols", value: (r) => r.uses.map((u) => u.title).join("; "), search: 1, column: { header: "Protocols", drop: 2 } },
425    ],
426  }),
427);
428
429/** What a reagent's cells say where the record states nothing, with the reason, so a gap is listed and not left blank. @param {ReagentRow} r */
430export function reagentGapText(r) {
431  const parts = [];
432  if (!r.preparedInLab && !r.supplier) parts.push(`supplier: ${r.supplierMissing ?? "not recorded"}`);
433  if (!r.preparedInLab && !r.catalogNumber) parts.push(`catalog number: ${r.catalogNumberMissing ?? "not recorded"}`);
434  if (r.preparedInLab && !r.recipe) parts.push(`recipe: ${r.recipeMissing ?? "not recorded"}`);
435  return parts;
436}
437
438/**
439 * The reagents as one markdown table for the twin, then every gap with its reason, so a machine reads what a person sees and what
440 * is still missing.
441 *
442 * @param {ReagentRow[]} reagents
443 * @param {string} origin
444 */
445export function reagentsMarkdown(reagents, origin) {
446  const link = (/** @type {ReagentRow} */ r) => (r.productUrl ? `[product](${r.productUrl})` : r.recipePath ? `[recipe](${origin}${r.recipePath})` : "");
447  const uses = (/** @type {ReagentRow} */ r) => r.uses.map((u) => `[${cell(u.title)}](${origin}${u.path})`).join(", ");
448  const lines = reagents.map((r) => `| ${cell(reagentLabel(r))} | ${cell(reagentSource(r))} | ${cell(r.catalogNumber)} | ${link(r)} | ${uses(r)} |`);
449  const gaps = reagents.flatMap((r) => reagentGapText(r).map((text) => `- ${r.name}, ${text}`));
450  return [
451    "| Reagent | Supplier | Catalog number | Link | Protocols |",
452    "| --- | --- | --- | --- | --- |",
453    ...lines,
454    ...(gaps.length > 0 ? ["", "Not found:", "", ...gaps] : []),
455  ].join("\n");
456}
457
458/**
459 * One reagent as markdown for its item twin: the same facts as its page, every gap with its reason, and the protocols that use it.
460 *
461 * @param {ReagentRow} r
462 * @param {string} origin
463 */
464export function reagentItemMarkdown(r, origin) {
465  const lines = [
466    r.abbreviation ? `- Abbreviation: ${r.abbreviation}` : "",
467    r.contents ? `- Contents: ${r.contents}` : "",
468    r.preparedInLab
469      ? `- Source: prepared in the lab${r.recipePath ? `, [recipe](${origin}${r.recipePath})` : `; recipe not found (${r.recipeMissing ?? "not recorded"})`}`
470      : `- Supplier: ${r.supplier ?? `not found (${r.supplierMissing ?? "not recorded"})`}`,
471    r.preparedInLab ? "" : `- Catalog number: ${r.catalogNumber ?? `not found (${r.catalogNumberMissing ?? "not recorded"})`}`,
472    r.productUrl ? `- Product page: ${r.productUrl}` : "",
473    "",
474    ...r.uses.map((u) => `- Used in: [${u.title}](${origin}${u.path})`),
475  ];
476  return `# ${r.name}\n\n${lines.join("\n").replace(/\n{3,}/g, "\n\n").trim()}\n`;
477}
478
479/* ------------------------------------------------------------------------------------------------ equipment */
480
481/**
482 * What the protocols do with an item, read from the protocols that name it in their equipment list (`equipment: <id>`). Nothing is
483 * stored on the item, so a protocol that names it later is listed with no edit to the record.
484 *
485 * @param {string} id
486 * @param {Array<{ path: string, title: string, equipment?: Array<{ name: string, item?: { id: string } | null }> }>} protocols
487 */
488export function equipmentUses(id, protocols) {
489  return protocols
490    .filter((protocol) => (protocol.equipment ?? []).some((e) => e.item?.id === id))
491    .map((protocol) => ({ path: protocol.path, title: protocol.title }));
492}
493
494/**
495 * An equipment item as the pages read it: the record's own fields, with a maker or rotor nobody has recorded said with its reason,
496 * and the protocols that use it, computed from the protocols.
497 *
498 * @param {import("./kinds.mjs").RegistryItem} item
499 * @param {Parameters<typeof equipmentUses>[1]} [protocols]
500 */
501export function equipmentRow(item, protocols = []) {
502  const f = /** @type {Record<string, unknown>} */ (item.fields);
503  return {
504    id: item.id,
505    name: item.name,
506    path: itemPath("equipment", item.id),
507    manufacturer: stated(f.manufacturer),
508    manufacturerMissing: missingReason(f.manufacturer),
509    rotor: stated(f.rotor),
510    rotorMissing: missingReason(f.rotor),
511    uses: equipmentUses(item.id, protocols),
512    draft: item.status === "draft",
513  };
514}
515
516/** @typedef {ReturnType<typeof equipmentRow>} EquipmentRow */
517
518/** The equipment as rows, each with the protocols that use it. @param {import("./kinds.mjs").RegistryItem[]} items @param {Parameters<typeof equipmentUses>[1]} protocols */
519export function equipmentRows(items, protocols) {
520  return items.filter((item) => item.kind === "equipment").map((item) => equipmentRow(item, protocols));
521}
522
523/** The equipment catalog: the one table, with the columns an item is read by. */
524export const EQUIPMENT_CATALOG = defineCatalog(
525  /** @type {import("capsomer/behaviour/catalog").CatalogDefinition<EquipmentRow>} */ ({
526    id: "equipment",
527    noun: ["item", "items"],
528    basePath: kindPath("equipment"),
529    itemKey: (e) => e.id,
530    defaultSort: "name",
531    pageSize: 50,
532    fields: [
533      { key: "name", label: "Equipment", value: (e) => e.name, search: 3, column: { header: "Equipment" }, sort: true },
534      { key: "manufacturer", label: "Manufacturer", value: (e) => e.manufacturer, facet: { kind: "many", order: "alpha" }, search: 1, column: { header: "Manufacturer", drop: 1 } },
535      { key: "rotor", label: "Rotor", value: (e) => e.rotor, search: 1, column: { header: "Rotor", drop: 2 } },
536      { key: "protocols", label: "Protocols", value: (e) => e.uses.map((u) => u.title).join("; "), search: 1, column: { header: "Protocols", drop: 1 } },
537    ],
538  }),
539);
540
541/** What an item's cells say where the record states nothing, with the reason. @param {EquipmentRow} e */
542export function equipmentGapText(e) {
543  const parts = [];
544  if (!e.manufacturer) parts.push(`manufacturer: ${e.manufacturerMissing ?? "not recorded"}`);
545  if (!e.rotor && e.rotorMissing) parts.push(`rotor: ${e.rotorMissing}`);
546  return parts;
547}
548
549/**
550 * The equipment as one markdown table for the twin, then every gap with its reason, so a machine reads what a person sees and what
551 * is still missing.
552 *
553 * @param {EquipmentRow[]} items
554 * @param {string} origin
555 */
556export function equipmentMarkdown(items, origin) {
557  const uses = (/** @type {EquipmentRow} */ e) => e.uses.map((u) => `[${cell(u.title)}](${origin}${u.path})`).join(", ");
558  const lines = items.map((e) => `| ${cell(e.name)} | ${cell(e.manufacturer)} | ${cell(e.rotor)} | ${uses(e)} |`);
559  const gaps = items.flatMap((e) => equipmentGapText(e).map((text) => `- ${e.name}, ${text}`));
560  return [
561    "| Equipment | Manufacturer | Rotor | Protocols |",
562    "| --- | --- | --- | --- |",
563    ...lines,
564    ...(gaps.length > 0 ? ["", "Not found:", "", ...gaps] : []),
565  ].join("\n");
566}
567
568/**
569 * One item of equipment as markdown for its item twin: who makes it, a centrifuge's rotor, every gap with its reason, and the
570 * protocols that use it.
571 *
572 * @param {EquipmentRow} e
573 * @param {string} origin
574 */
575export function equipmentItemMarkdown(e, origin) {
576  const lines = [
577    `- Manufacturer: ${e.manufacturer ?? `not found (${e.manufacturerMissing ?? "not recorded"})`}`,
578    e.rotor ? `- Rotor: ${e.rotor}` : e.rotorMissing ? `- Rotor: not found (${e.rotorMissing})` : "",
579    "",
580    ...e.uses.map((u) => `- Used in: [${u.title}](${origin}${u.path})`),
581  ];
582  return `# ${e.name}\n\n${lines.join("\n").replace(/\n{3,}/g, "\n\n").trim()}\n`;
583}
584
585/* ------------------------------------------------------------------------------------------------ inventory */
586
587/** A phage's host as plain words: the table's short form without its emphasis marks. @param {string | null} host */
588function hostWords(host) {
589  const entry = host ? /** @type {Record<string, { short: string }>} */ (HOSTS)[host] : null;
590  return entry ? entry.short.replaceAll("*", "") : null;
591}
592
593/** The kind's label in the inventory's words, singular. @param {string} kind */
594export function kindLabel(kind) {
595  if (kind === "phage") return "Phage";
596  const singular = KINDS[kind]?.singular ?? kind;
597  return singular.charAt(0).toUpperCase() + singular.slice(1);
598}
599
600/**
601 * One line about an item, read from its own record: what a reader scanning the inventory wants beside the name.
602 *
603 * @param {import("./kinds.mjs").RegistryItem} item
604 */
605function summaryOf(item) {
606  if (item.kind === "primer") {
607    const row = primerRow(item);
608    return [row.direction ? `${DIRECTION_LABELS[row.direction]?.toLowerCase() ?? row.direction} primer` : "primer", row.target, row.length ? `${row.length} nt` : null]
609      .filter(Boolean)
610      .join(", ");
611  }
612  if (item.kind === "strain") {
613    const f = /** @type {Record<string, unknown>} */ (item.fields);
614    return [stated(f.organism), stated(f.collection) && stated(f.collection_number) ? `${stated(f.collection)} ${stated(f.collection_number)}` : null].filter(Boolean).join(", ");
615  }
616  if (item.kind === "equipment") {
617    return [stated(/** @type {Record<string, unknown>} */ (item.fields).manufacturer)].filter(Boolean).join(", ");
618  }
619  if (item.kind === "reagent") {
620    const f = /** @type {Record<string, unknown>} */ (item.fields);
621    return [stated(f.abbreviation), stated(f.contents), f.prepared_in_lab === true ? "prepared in lab" : stated(f.supplier)].filter(Boolean).join(", ");
622  }
623  return "";
624}
625
626/**
627 * The inventory's rows: every published registry item, and every phage read from the phages table. A phage is its own
628 * table's and page's, so its row links to its section on /research/phages and states nothing the table does not.
629 *
630 * @param {import("./kinds.mjs").RegistryItem[]} items
631 * @param {Array<{ name: string, year: number, host: string | null, county: string | null }>} phages
632 */
633export function inventoryRows(items, phages) {
634  return [
635    ...items.map((item) => ({
636      key: `${item.kind}/${item.id}`,
637      kind: item.kind,
638      kindLabel: kindLabel(item.kind),
639      name: item.name,
640      summary: summaryOf(item),
641      // A kind that is one table has no page for the item: its row goes to the table.
642      path: hasItemPage(item.kind) ? itemPath(item.kind, item.id) : kindPath(item.kind),
643    })),
644    ...phages.map((phage) => ({
645      key: `phage/${phage.name.toLowerCase()}`,
646      kind: "phage",
647      kindLabel: kindLabel("phage"),
648      name: phage.name,
649      summary: [`found in ${phage.year}`, hostWords(phage.host), phage.county].filter(Boolean).join(", "),
650      path: `/research/phages#${phage.name.toLowerCase()}`,
651    })),
652  ];
653}
654
655/** @typedef {ReturnType<typeof inventoryRows>[number]} InventoryRow */
656
657/** Where a kind sits in the inventory's order: the registry's kinds as defined, then the phages. @param {string} kind */
658function kindRank(kind) {
659  const at = Object.keys(KINDS).indexOf(kind);
660  return at === -1 ? Object.keys(KINDS).length : at;
661}
662
663/** The master inventory catalog: every item of every kind, filtered by kind. */
664export const INVENTORY = defineCatalog(
665  /** @type {import("capsomer/behaviour/catalog").CatalogDefinition<InventoryRow>} */ ({
666    id: "lab",
667    noun: ["item", "items"],
668    basePath: LAB_PATH,
669    itemKey: (row) => row.key,
670    defaultSort: "kind",
671    pageSize: 50,
672    fields: [
673      { key: "name", label: "Name", value: (row) => row.name, search: 3, column: { header: "Name" }, sort: true },
674      {
675        key: "kind",
676        label: "Kind",
677        value: (row) => row.kind,
678        facet: { kind: "many", general: true, label: kindLabel },
679        column: { header: "Kind", drop: 2 },
680        // The registry's kinds in the order they are defined, the phages after them, then by name: the default order
681        // reads the lab's own records first and never buries them behind seventy-five phages.
682        sort: { compare: (a, b) => kindRank(a.kind) - kindRank(b.kind) || a.name.localeCompare(b.name, "en", { numeric: true }) },
683        search: 1,
684      },
685      { key: "summary", label: "About", value: (row) => row.summary, search: 2, column: { header: "About", drop: 1 } },
686    ],
687  }),
688);
689
690/* ------------------------------------------------------------------------------------------------ markdown twins */
691
692const cell = (/** @type {string | number | null} */ value) => String(value ?? "").replaceAll("|", "\\|");
693
694/**
695 * The inventory as a markdown table, for the twin: the facts a person sees.
696 *
697 * @param {InventoryRow[]} rows
698 * @param {string} origin
699 */
700export function inventoryMarkdown(rows, origin) {
701  const lines = rows.map((row) => `| [${cell(row.name)}](${origin}${row.path}) | ${cell(row.kindLabel)} | ${cell(row.summary)} |`);
702  return ["| Name | Kind | About |", "| --- | --- | --- |", ...lines].join("\n");
703}
704
705/**
706 * A site on a reference in words, as the page and the twin state it: its span in the accession's own coordinates, its
707 * strand, and its mismatches counted from the primer's 5′ end, so a primer that binds only imperfectly says so.
708 *
709 * @param {{ strand: "+" | "-", start: number, end: number, mismatches: number, mismatchPositions: number[] }} site
710 */
711export function siteText(site) {
712  const n = site.mismatches;
713  const mismatch =
714    n === 0
715      ? "no mismatches"
716      : `${n} mismatch${n === 1 ? "" : "es"} (primer base${n === 1 ? "" : "s"} ${site.mismatchPositions.join(", ")}, counted from its 5′ end)`;
717  return `${site.start} to ${site.end}, ${site.strand} strand, ${mismatch}`;
718}
719
720/**
721 * The span of a product on its reference and the sites that make it, in words.
722 *
723 * @param {{ length: number, start: number, end: number }} product
724 */
725export function productSpanText(product) {
726  return `${product.length} bp, ${product.start} to ${product.end}`;
727}
728
729/**
730 * The primers as a markdown table for the twin, with the computed columns beside the stored ones.
731 *
732 * @param {PrimerListRow[]} primers
733 * @param {string} origin
734 */
735export function primersMarkdown(primers, origin) {
736  const lines = primers.map(
737    (p) =>
738      `| [${cell(p.name)}](${origin}${p.path}) | \`${p.sequence ?? ""}\` | ${cell(p.direction)} | ${cell(p.target)} | ${cell(p.length)} | ${cell(p.tm)} | ${cell(productText(p.product))} |`,
739  );
740  return [
741    "| Primer | Sequence (5′ to 3′) | Direction | Target | Length (nt) | Tm estimate (°C) | Product (computed) |",
742    "| --- | --- | --- | --- | --- | --- | --- |",
743    ...lines,
744  ].join("\n");
745}
746
747/**
748 * The Tm sentence, the sentence that says it is not an annealing temperature, and the calculator that gives one, in one
749 * place for the page and the twin (test/registry-tm.test.mjs: no page presents a computed Tm as the annealing temperature).
750 */
751export function tmNote() {
752  return { statement: tmStatement(), annealing: annealingSentence(), calculator: NEB_TM_CALCULATOR, conditions: TM_CONDITIONS };
753}
754
755/**
756 * One primer as markdown for the twin: the same facts the page states, with the computed ones computed, and what could not be
757 * found said with its reason rather than left out.
758 *
759 * @param {PrimerRow} primer
760 * @param {PrimerRow[]} primers every published primer, for the mate and the pair's product
761 * @param {Array<{ path: string, title: string }>} usedBy
762 * @param {string} origin
763 */
764export function primerMarkdown(primer, primers, usedBy, origin) {
765  const mate = mateOf(primer, primers);
766  const pair = pairProduct(primer, primers);
767  const published = primer.publishedIn
768    ? `${primer.publishedIn}${primer.publishedDoi ? ` ([doi:${primer.publishedDoi}](https://doi.org/${primer.publishedDoi}))` : primer.publishedUrl ? ` (${primer.publishedUrl})` : ""}`
769    : null;
770  const lines = [
771    primer.sequence ? `- Sequence (5′ to 3′): \`${primer.sequence}\`` : "",
772    primer.reverseComplement ? `- Reverse complement (5′ to 3′): \`${primer.reverseComplement}\`` : "",
773    primer.direction ? `- Direction: ${primer.direction}` : "",
774    primer.target ? `- Target: ${primer.target}` : "",
775    primer.set ? `- Set: ${primer.set}` : "",
776    mate ? `- Pairs with: [${mate.name}](${origin}${mate.path})` : "",
777    primer.length ? `- Length: ${primer.length} nt` : "",
778    primer.gcPercent !== null ? `- GC content: ${primer.gcPercent}%` : "",
779    primer.tm !== null ? `- Melting temperature estimate (Tm): ${primer.tm} °C` : "",
780    `- Annealing temperature: depends on the polymerase; use the [${NEB_TM_CALCULATOR.name}](${NEB_TM_CALCULATOR.url})`,
781    "",
782    "## In the literature",
783    "",
784    `- Published in: ${published ?? `not found (${primer.publishedInMissing ?? "not recorded"})`}`,
785    `- Name in the paper: ${primer.publishedName ?? `not found (${primer.publishedNameMissing ?? "not recorded"})`}`,
786    primer.publishedSequence
787      ? `- Sequence in the paper: \`${primer.publishedSequence}\` (${primer.matchesPublished ? "the stored sequence is identical" : "DIFFERS from the stored sequence"})`
788      : `- Sequence in the paper: not found (${primer.publishedSequenceMissing ?? "not recorded"})`,
789    primer.publishedProduct
790      ? `- Product in the paper: ${primer.publishedProduct}`
791      : primer.direction === "forward"
792        ? `- Product in the paper: not found (${primer.publishedProductMissing ?? "not recorded"})`
793        : "",
794    "",
795    "## On the reference",
796    "",
797    primer.placement
798      ? `- Reference: ${primer.placement.reference.id} (${primer.placement.reference.description}), computed from the sequence`
799      : primer.reference
800        ? `- Reference: ${primer.reference}; the primer binds it nowhere within ${MAX_MISMATCHES} mismatches`
801        : "- Reference: none recorded",
802    ...(primer.placement ? primer.placement.sites.map((site) => `- Position: ${siteText(site)}`) : []),
803    ...(pair ? pair.products.map((product) => `- Product (computed, with ${mate?.name ?? "its pair"}): ${productSpanText(product)}`) : []),
804    "",
805    ...usedBy.map((protocol) => `- Used in: [${protocol.title}](${origin}${protocol.path})`),
806  ];
807  return `# ${primer.name}\n\n${lines.join("\n").replace(/\n{3,}/g, "\n\n").trim()}\n${primer.tm !== null ? `\n${tmNote().statement} ${tmNote().annealing}\n` : ""}`;
808}